Skip to main content
Skip Navigation LinksHome  Extending the Spotfire Platform  Common Tasks and Idioms  Spotfire Statistics Services Primer (C#)

©Spotfire 2011

Spotfire Statistics Services Primer (C#)

Spotfire Statistics Services includes the S-PLUS engine, which processes expressions or functions, provides the ability to administer the jobs submitted for execution and facilitates access to the results generated via standard WebDAV interface.

Overview

Spotfire Statistics Services functionality is exposed as a set of RESTful resources, which are consumed by C# client API implementation classes that encapsulate access to those resources. The following table describes the C# client APIs provided:

API Description
Administration Client API Provides access to job management tasks such as displaying job lists, interrupting job runs, and purging jobs. Note that access to certain Administration methods might be restricted to users with administrative privileges only. See your system administrator for more information.
Function Client API Provides access to S functions in libraries and packages stored on the server. Use the IFunctionClient.Eval() method, passing as its arguments an S function, its library or package, its arguments, and its dataset. (Optionally, you can specify that you want the function to run asychronously, and you can schedule a start time for the run. ) The server returns the SplusDataResult object to the client.
Expression Client API Provides access to the S-PLUS engine on the server. Use the IExpressionClient.Eval() method, with an S expression as a string argument, to send the expression to the service. Optionally, you can specify that you want the expression to run asynchronosly, and you can schedule a start time for the run.
The service parses the string, and the S engine evaluates the expression. If the engine finds no error in the expression, it returns the job resulting from the evaluation in an SplusDataResult object.
WebDAVClient API Provides access to the resources stored in a WebDAV directory structure on the server. The WebDAV client API represents a client that invokes methods available in the WebDAV service API exposed by Spotfire Statistics Services. It can be obtained using the ClientFactory class.
You can use WebDAV to create folders on the server, retrieve the contents of folders, upload and download files to folders on the server, move, copy and delete files, or get and set file properties.
The IWebDavClient interface provides a method list with short descriptions
Domain API The Domain API contains the classes for the S-PLUS Domain. It defines S-PLUS objects, classes, and data types, enums, delegates, and interfaces used by the Administration, Function, and Expression client interfaces.
See Tibco.SplusServer.Api.Domain namespace for a list and short description of each of its defined classes.

Obtaining an Instance of a Given Client

The C# client API implements a standard Factory design pattern for client instance creation. ClientFactory is the class that implements a factory and provides a way to obtain a client object of a given type by calling a relevant method. For example:

string serviceUrl = "http://localhost:8080/SplusServer";
string username   = "myusername";
string password   = "mypassword";
IAdministrationClient api = ClientFactory.GetAdministrationClient(serviceUrl, username, password);

Errors

As you implement your .NET application using the C# API, you should consider two types of problems:

  • API Exceptions (that is, problems with server communication, user validation, or URLs).
  • S errors (that is, problems with the S expressions or functions).

The Tibco.SplusServer.Api.Domain.Exceptions namespace contains classes for catching and handling API exceptions. The Administration Client API, the Expression Client API, the Function Client API, and the WebDAV API all take advantage of these classes.

Exception Handling

The Domain API includes exception classes, which are designed to capture problems with server communication, user validation, or URL information. Refer to the Tibco.SplusServer.Api.Domain.Exceptions namespace for a list of these classes.

When an exception occurs, the API calls the constructor to create the specific type of exception object. (That is, you never call the constructor explicitly.) This object includes a text message to inform the user of the nature of the problem and (optionally) a suggested action to resolve the problem. This text message is held in the Message property of the exception object. If no message is provided, the API provides a default message.

S Errors

If the S code that you pass to the service contains errors, the returned SplusDataResult object contains either a Spotfire S+ error message or a warning.

Note that Spotfire S+ programmers can supply error messages and warnings using the S-PLUS functions stop() and warning(). For more information about these functions, see the Spotfire S+ Language Reference.

Managing Jobs

After the engine runs the request, it returns the jobs via the server's communication layer. The job is returned in the SplusDataResult.

A job includes properties such as job status, job ID, date created, and so on. In addition to these properties, the successfully-completed job contains a list of S-PLUS objects returned and the directory where the result files are expected. Also, it can include error messages, warnings, and logged text.

You can design your .NET application to handle the returned job and display it in the most appropriate form. For example, you might want to display a graph, or you might want to provide just a URL link to the graph file. If your request returns an SplusDataResult containing data (for example, a vector, a list, a matrix, or a data frame), those can be found in the ReturnValue property of the object returned, which contains a list of these objects.

Note

The Spotfire Statistics Services C# APIs follow the Microsoft® convention for strong named assemblies. For more information, refer to the Strong-Named Assemblies Microsoft® Developer Network article.