SWP with TopBraid Live

The SWP servlet

SWP is supported by a TopBraid Live servlet. The tbl/swp (formerly: tbl/uispin) servlet can be used to generate any textual format, including HTML, SVG and JSON based on UISPIN definitions. For example, on the built-in TBL server of TopBraid Composer, with any file open in TBC, open a web browser and navigate to:

http://localhost:8083/tbl/swp?_resource=owl:Thing

Parameters (all optional):

• _resource: qname or URI of the resource to render.
• _base: the URI of the model to open. Can be set to resource to use the same URI as the resource (shorter names). Can be left blank. In TBC-ME blank will operate on the currently open model, otherwise it will try to open a matching file (with the namespace of the resource as its base URI). Can also be one of the short names specified in the TBL server configuration parameters.
• _withImports: if set to true, then the _base argument will be interpreted together with its owl:imports.
• _matchIds: comma-separated list of id types to match.
• _snippet: true to only return an (HTML) snippet without HTML, HEAD and BODY tags.
• _server: the URL of the TBL server, used by ui:createLink. Example: http://localhost:8083/tbl/
• _view: ID of the view to render, e.g. its qname.
• _viewClass: qname or URI of the SWP element to render.
• _cache: true to activate caching for this request.
• _progressId: a unique identifier for a progress monitor (see below)
• _fileUpload: if true then files uploaded as part of a multi-part HTTP request will be copied into the workspace as temporary files. The name of the corresponding file will be assigned to the argument variable. For example, define a service with an argument arg:file of type string and create a web form that uploads files as "file". The variable ?file will then contain the path to the temp file in the workspace. You can then use the function smf:baseURI to get the URI of that file, e.g. to open it using <ui:setContext ui:queryGraph="..." />. This is particularly useful for Excel files.
• All other arguments will become pre-bound variables in the UISPIN view, e.g. name=TEST will bind ?name to "TEST"^^xsd:string.

The TopBraid Live Server Configuration Parameters page provides an option that changes the behavior of ui:createLink so that all links are generated as absolute URLs.

The SWP servlet supports a design pattern allowing clients to monitor the progress of a long-running operation. If you have an SWP servlet request that may take a while, you can pass in an argument such as _progressId=0.1234 (often created using Math.random() in client-side JavaScript code). This will instruct the server that it shall provide status updates under the given id. The client can then spawn off another thread (e.g. via JavaScript setTimeout) that periodically pulls update on the progress from the servlet. There is a pre-defined servlet for this, e.g.

tbl/swp?_viewClass=swa:ProgressJSONCallback&id=0.1234

would return a JSON object with attributes task and/or subTask containing status updates created by the servlet. The SWP elements ui:task and ui:subTask can be used for this purpose.

Working with stand-alone SWP (*.swp) files

It is also possible to create stand-alone SWP pages that are simply text (HTML) files with embedded SWP control elements. Any file ending with .swp will be automatically recognized and executed with an SWP servlet. For example, the file MyFile.swp in the folder MyFolder of project MyProject can be executed from a web browser as http://localhost:8083/tbl/MyFolder/MyFile.swp. Use the wizard New > SPARQL Web Pages File to create empty files to begin with. If not already done, associate .swp files with the Eclipse HTML editor for best editing support. To do so, open the Eclipse Preferences and go to General > Content Types. Then navigate to Text > HTML and add the ending *.swp to the file associations.

Files ending with .json.swp will be automatically handled as if the _format=json, i.e. it will return with the JSON mime type. Files ending with .xml.swp will be automatically handled as if the _format=xml, i.e. it will return with an XML mime type.

.swp files can accept parameters from the HTTP request, using the SPARQL function ui:param. For example, ui:param('age', xsd:integer) looks for the parameter from the following request URL http://localhost:8083/tbl/MyFolder/MyFile.swp?age=42 and converts it into an integer literal. If no second argument is provided, then the system will return a string literal. For URI resources, use any other class name, including rdfs:Resource.

The Lib servlet

TBL supports a mechanism to store auxiliary files such as JavaScript libraries or images in the workspace, and then reference them from UISPIN pages. You need to create folder ending with .www, such as mylibs.www and then reference it with relative URLs such as lib/mylibs. The part of the name before the .www will be used to identify which root folder to use.

The Describe servlet

TopBraid Live also provides a servlet for simple linked data browsing. The servlet describe will render a given resource, and either return a human-readable rendering (using UISPIN), or triples in either RDF/XML or Turtle syntax. The return type is either specified in the Accept header (application/rdf+xml or text/turtle) or using an explicit argument _format. Try following example:

http://localhost:8083/tbl/describe?_format=application%2Frdf%2Bxml&_resource=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23subClassOf

You can set up your web server to rewrite incoming request URLs so that they call the describe servlet with the _resource parameter.