OpenSpirit Web Services User's Guide · 2016. 9. 14. · JAX-RS specification (The Java API for RESTful Web Services) is used to define the services. The Jersey implementation of

TIBCO OpenSpirit® Web Services User’s Guide Software Release 1.0.0

September 2016

Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENTIS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, OpenSpirit, and TIBCO OpenSpirit Web Services are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE RELEASE NOTES FOR THE AVAILABILITY OF THIS SOFTWARE VERSIONON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2000-2016 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

iii

Table of Contents Introduction ..................................................................................................................... 5

Technology utilized by TOWS ....................................................................................... 5

OpenSpirit Concepts ...................................................................................................... 5

Connecting with TIBCO Resources ............................................................................... 5

How to Join TIBCOmmunity ..................................................................................... 5

How to Access All TIBCO Documentation ................................................................. 6

How to Contact TIBCO Support ................................................................................. 6

Installation and Configuration .......................................................................................... 7

Installation and Configuration ....................................................................................... 7

Installation Requirements ........................................................................................... 7

OpenSpirit Runtime Configuration ............................................................................. 7

Application Server Account ........................................................................................ 8

TOWS Services Deployment ...................................................................................... 8

Tomcat Deployment ......................................................................................................... 9

Deploying WAR files into Tomcat ................................................................................. 9

Integrated Tomcat Windows Authentication using WAFFLE ........................................ 9

Jetty Deployment ........................................................................................................... 11

Automatic Jetty Web Application Deployment Model ................................................. 11

Separate jetty.base ....................................................................................................... 11

Verifying Jetty Deployment ......................................................................................... 13

Integrated Jetty Windows Authentication using WAFFLE ........................................... 13

Authentication ............................................................................................................... 15

Behavior With Authentication ..................................................................................... 15

Behavior Without Authentication ................................................................................ 15

API Usage...................................................................................................................... 16

Http request methods ................................................................................................... 16

JSON .......................................................................................................................... 16

OpenSpirit Services ..................................................................................................... 16

/openspirit ............................................................................................................... 16

/carto ....................................................................................................................... 17

/data ........................................................................................................................ 17

/entity ...................................................................................................................... 18

iv

/event ...................................................................................................................... 20

/metamodel ............................................................................................................. 21

/unit ........................................................................................................................ 21

Example Web Application .............................................................................................. 23

Unit Service Example Overview .................................................................................. 24

Carto Service Example Overview ................................................................................. 24

Data and Metamodel Service Example Overview ......................................................... 25

Event Service Example Overview ................................................................................ 28

Sending Data Selection Events .................................................................................. 30

Sending GIS Feature Selection Events....................................................................... 30

Entity Service Example Overview ................................................................................ 31

Selecting Entities ...................................................................................................... 32

Sending Data Selection Events .................................................................................. 33

Viewing Entities in the Connect Sub-Surface Viewer ................................................. 34

Image Requests ........................................................................................................ 34

Bulk Data Requests .................................................................................................. 35

Custom Entity Data Sources ........................................................................................... 36

Creating Custom Entity Data Sources .......................................................................... 37

EntityProvider Class ................................................................................................. 37

Registering an EntityProvider ................................................................................... 37

Entity Datakey Strings .............................................................................................. 38

LAS Custom Entity Data Source Example ................................................................... 39

Introduction | 5

Introduction This TIBCO OpenSpirit® Web Services (TOWS) User Guide is intended to be used by web application developers that would like to use one or more of the OpenSpirit services in their web application, or by IT administrators responsible for installing, configuring, and maintaining a TOWS installation. The TOWS product exposes the most commonly used OpenSpirit SDK APIs as a set of RESTful web services. This guide describes the OpenSpirit services exposed by TOWS and describes how to install. configure, administer and use the services in a web application. An example JavaScript application is provided to aid web application developers.

Technology utilized by TOWS The JAX-RS specification (The Java API for RESTful Web Services) is used to define the services. The Jersey implementation of the specification is used to implement the REST services in a servlet container. The servlet scans the Java classes for REST resources and handles incoming HTTP requests by calling the appropriate services to generate responses.

The Jackson JSON Processor is used for serializing/deserializing JSON data format.

The TOWS RESTful API is documented using OpenAPI (formerly Swagger) 2.0 specification. The API is described in a JSON file which is used to generate Java classes with JAX-RS and Swagger annotations. The Swagger-UI tool can then be used to display and test the API.

OpenSpirit Concepts IT administrators and web application developers should have a good understanding of OpenSpirit concepts and architecture prior to using TOWS. The TIBCO OpenSpirit® Runtime User's Guide should be reviewed and understood prior to working with TOWS. IT administrators are encouraged to attend the OpenSpirit administrator training course and web application developers are encouraged to attend the OpenSpirit developer training class.

Connecting with TIBCO Resources

How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts, a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

OpenSpirit Web Services User's Guide

https://jax-rs-spec.java.net/

https://jersey.java.net/

https://github.com/FasterXML/jackson-jaxrs-providers

https://openapis.org/

https://docs.tibco.com/pub/openspirit-runtime/4.2.0/doc/pdf/TIB_os-rt_4.2.0_userguide.pdf


http://www.tibcommunity.com/

6 | Introduction

How to Access All TIBCO Documentation After you join TIBCOmmunity , you can access the documentation for all supported product versions here:

https://docs.tibco.com

How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows.

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site: https://support.tibco.com Entry to this site requires a user name and password. If you do not have a user name, you can request one.


https://docs.tibco.com/

http://www.tibco.com/services/support

https://support.tibco.com/

Installation and Configuration | 7

Installation and Configuration Installation and Configuration These instructions describe a basic installation and configuration of TOWS. Please refer to the documentation for your Tomcat or Jetty web application server if you need additional information.

Installation Requirements

Prerequisite Software TIBCO OpenSpirit Runtime v4.1.0 or higher (OpenSpirit data connector licenses are also required to use the data service and the entity service).

Tomcat 8.5.x or Jetty 9.3.x

Supported Platforms TOWS is supported on the same platforms that are supported by the TIBCO OpenSpirit Runtime.

Disk Space Requirements The extracted WAR file needed for TOWS consumes approximately 16 MB of disk.

The extracted WAR file needed for the TOWS SDK consumes approximately 9 MB of disk.

Memory Requirements The amount of memory needed for TOWS is highly variable depending on the number of concurrent users being served, the number of data sources being accessed, and the amount of data being accessed. Please refer to the OpenSpirit Runtime documentation for more information about OpenSpirit resource requirements.

OpenSpirit Runtime Configuration The TIBCO OpenSpirit Runtime needs to be installed on the host running the application server (Jetty or Tomcat). The account running the Jetty or Tomcat application server needs to be an account that can access an OpenSpirit master installation.

The environment variable OSP_CONFIG needs to be set to point to the config directory of the OpenSpirit master installation you would like TOWS to use if your application server is running on Linux. The application server needs to be restarted to pick up this new environment variable. No environment variable is needed if your application server is running on Windows. Please see the OpenSpirit Runtime Installation Guide for more information about the installation, configuration, and administration of your OpenSpirit Runtime.


8 | Installation and Configuration

Application Server Account If TOWS will be deployed to use authentication, the application server account needs to be granted the Impersonate OpenSpirit User right by the administrator of your OpenSpirit runtime. This right allows the application server account to access OpenSpirit user information needed to determine the data sources and projects that the authenticated user has access to. Please see the User Manager section of the OpenSpirit Desktop User Guide for information about granting OpenSpirit user rights. The application server account also needs to have access to underlying datasource projects that will be accessed by the TOWS data and entity services. The OpenSpirit host account and data source settings for the application server account needs to be configured using the User Setup Wizard tool in the OpenSpirit Desktop.

TOWS Services Deployment The TOWS services are packaged as a WAR file named openspirit.war. A second WAR file named openspirit-sdk.war is also provided which contains documentation and examples to aid web application developers wanting to use the TOWS services. The TOWS SDK WAR file is typically deployed in a web application container used for development. The SDK WAR file does not need to be deployed in your production environment.

The URL to access the SDK documentation is:

http://<host>:<port>/openspirit-sdk

Where <host> is the name of the host computer running the application server you deployed the openspirit-sdk.war into, and <port> is the port number of your application server.

The following section describe how to deploy the TOWS WAR files in a Tomcat or Jetty web application container. These instructions cover basic deployment configurations. Refer to your application server documentation for details of deploying and configuring WAR files in a more sophisticated environment.


Tomcat Deployment | 9

Tomcat Deployment This section describes steps in deploying TOWS into a Tomcat web application container.

Deploying WAR files into Tomcat Copy the war files openspirit.war and openspirit-sdk.war to the <tomcat-home>/webapps directory. To verify the deployment of TOWS, open URL http://<tomcat host>:<port>/openspirit/configInfo in your web browser substituting your Tomcat installation's host and port. It should give you the OpenSpirit installation host and port the web service is connected to, along with your OpenSpirit installation version information.

Integrated Tomcat Windows Authentication using WAFFLE A web server can be setup to run in unauthenticated or authenticated mode. This section describes how to configure Tomcat to use the WAFFLE Servlet Security Filter for integrated Windows authentication. Tomcat must be running on Windows.

1. Download and copy the required WAFFLE jar files for your specific Tomcat version along with its dependencies to your <tomcat-home>\lib folder. The required files for the specific Tomcat version can be downloaded from http://mvnrepository.com/artifact/com.github.dblock.waffle.

2. Add the following XML snippet to the <tomcat-home>\conf\web.xml file: <filter> <filter-name>SecurityFilter</filter-name> <filter-class>waffle.servlet.NegotiateSecurityFilter</filter-class> <init-param> <param-name>allowGuestLogin</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>waffle.servlet.spi.NegotiateSecurityFilterProvider/protocols</param-name> <param-value>NTLM</param-value> </init-param> </filter> <filter-mapping> <filter-name>SecurityFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>


http://mvnrepository.com/artifact/com.github.dblock.waffle

10 | Tomcat Deployment

3. Restart Tomcat.

4. To verify, open URL http://<tomcat host>:<port>/openspirit/configInfo in your web browser substituting your Tomcat installation's host and port. The response should have isAuthenticated set to true.

For more information about configuring the WAFFEL Servlet Security Filter, please visit https://github.com/dblock/waffle/blob/master/Docs/ServletSingleSignOnSecurityFilter.md.

For information on other Windows authentication, please visit https://tomcat.apache.org/tomcat-9.0-doc/windows-auth-howto.html


https://github.com/dblock/waffle/blob/master/Docs/ServletSingleSignOnSecurityFilter.md


https://tomcat.apache.org/tomcat-9.0-doc/windows-auth-howto.html

Jetty Deployment | 11

Jetty Deployment This section describes how to deploy TOWS into a Jetty web application container.

For documentation on deploying and configuring Jetty, please visit

http://www.eclipse.org/jetty/documentation/current/index.html

For more information on Jetty, please visit

http://www.eclipse.org/jetty/

For more information on how to deploy web applications to Jetty, please visit

https://wiki.eclipse.org/Jetty/Howto/Deploy_Web_Applications

Automatic Jetty Web Application Deployment Model For quick deployment into your existing Jetty installation (referred to as ${jetty.home}), copy the war files openspirit.war and openspirit-sdk.war to your ${jetty.home}/webapps.

Optionally, the content of openspirit.war may be extracted into ${jetty.home}/webapps/openspirit and content of openspirit-sdk.war into ${jetty.home}/webapps/openspirit-sdk directory. Set the jetty.http.port attribute in the ${jetty.home}/start.ini file. Jetty’s deployment scanner will find the war files or their content and deploy them under a Context path of the same name as the war file or the directory name: <jetty host>:<jetty.http.port>/openspirit and <jetty host>:<jetty.http.port>/openspirit-sdk.

Separate jetty.base If the Jetty server is hosting multiple web applications, then the recommendation is to create a jetty.base for the OpenSpirit web service with its own configuration:

1. Create a directory called openspirit-base and that will be your ${jetty.base}.

2. Copy the start.ini file from the Jetty home directory (referenced as ${jetty.home}).

3. Edit the start.ini to start the service with the following modules: • ext • resources • server • http (set jetty.http.port to the port you want to start the web service on) • deploy • jsp • websocket • jstl

4. Create a directory called webapps in the openspirit-base directory.


http://www.eclipse.org/jetty/documentation/current/index.html

http://www.eclipse.org/jetty/

https://wiki.eclipse.org/Jetty/Howto/Deploy_Web_Applications

12 | Jetty Deployment

5. In the webapps directory create a file called openspirit.xml with the following content: <?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath"><SystemProperty name="hostContext" default="/openspirit"/></Set> <Set name="war"><SystemProperty name="jetty.base"/>/webapps/openspirit.war</Set> <Set name="defaultsDescriptor"><SystemProperty name="jetty.home"/>/etc/webdefault.xml</Set> <Set name="overrideDescriptor"><SystemProperty name="jetty.base"/>/etc/override-web.xml</Set> </Configure> Additional Jetty configuration properties can be set in the openspirit.xml file, such as extractWar, tempDirectory, persistTempDirectory.

6. In the webapps directory create a file called openspirit-sdk.xml with the following content: <?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath"><SystemProperty name="hostContext" default="/openspirit-sdk"/></Set> <Set name="war"><SystemProperty name="jetty.base"/>/webapps/openspirit-sdk.war</Set> <Set name="defaultsDescriptor"><SystemProperty name="jetty.home"/>/etc/webdefault.xml</Set> <Set name="overrideDescriptor"><SystemProperty name="jetty.base"/>/etc/override-web.xml</Set> </Configure> Additional Jetty configuration properties can be set in the openspirit.xml file, such as extractWar, tempDirectory, persistTempDirectory.

7. Copy the war files openspirit.war and openspirit-sdk.war to the openspirit-base/webapps directory.

8. From the openspirit-base directory, start the server with the command: java -jar ${jetty.home}/start.jar


Jetty Deployment | 13

Verifying Jetty Deployment To verify the deployment of TOWS, open URL http://<jetty host>:<jetty.http.port>/openspirit/configInfo in your web browser substituting your Jetty installation's host and port. The response to the request will have the host, port, and version of the OpenSpirit Runtime installation that TOWS is connected to. It also gives the authentication mode of the web service.

For documentation and examples on using TOWS, open URL http://<jetty host>:<jetty.http.port>/openspirit-sdk in your web browser substituting your Jetty installation's host and port.

Integrated Jetty Windows Authentication using WAFFLE Jetty can be setup to run in unauthenticated or authenticated mode. This section describes how to configure Jetty to use the Waffle Servlet Security Filter for integrated Windows authentication. Jetty must be running on Windows.

1. Create a lib\ext folder under the ${jetty.base}\openspirit-base.

2. Download the required WAFFLE jar files for your specific Jetty version along with its dependencies and place them in the lib\ext folder created in step 1. The required files for the specific Jetty version can be downloaded from http://mvnrepository.com/artifact/com.github.dblock.waffle.

3. Create a file called override-web.xml in the openspirit-base/etc folder, with the following content: <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd" metadata-complete="false" version="3.1"> <filter> <filter-name>SecurityFilter</filter-name> <filter-class>waffle.servlet.NegotiateSecurityFilter</filter-class> <init-param> <param-name>allowGuestLogin</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>waffle.servlet.spi.NegotiateSecurityFilterProvider/protocols</param-name>


http://mvnrepository.com/artifact/com.github.dblock.waffle

14 | Jetty Deployment

<param-value>NTLM</param-value> </init-param> </filter> <filter-mapping> <filter-name>SecurityFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> </web-app>

4. In both openspirit-base/webapps/openspirit.xml and openspirit-sdk.xml files, add the following line: <Set name="overrideDescriptor"><SystemProperty name="jetty.base"/>/etc/override-web.xml</Set>

5. To verify that authentication has been turned on open URL http://<jetty host>:<jetty.http.port>/openspirit/configInfo in your web browser substituting your Jetty installation's host and port. The response should have isAuthenticated set to true.

For more information about configuring the WAFFEL Servlet Security Filter, please visit https://github.com/dblock/waffle/blob/master/Docs/ServletSingleSignOnSecurityFilter.md.




Authentication | 15

Authentication The way TOWS interacts with the OpenSpirit runtime differs depending on how authentication has been configured in the Tomcat or Jetty container that TOWS is running in. An understanding of the OpenSpirit user concept along with OpenSpirit user rights is required in order to understand how TOWS interacts with the OpenSpirit runtime. The TIBCO OpenSpirit® Runtime User's Guide should be reviewed and understood prior to working with TOWS.

See the Installation and Configuration section of this guide for information about configuring authentication.

Behavior With Authentication The user credentials supplied with each REST request is used to identify the OpenSpirit runtime user that represents the requesting web user if TOWS is configured with authentication enabled. The user name in the REST request is matched with the primary or secondary account of an existing OpenSpirit user. The requesting web user is registered as a new OpenSpirit user if no matching OpenSpirit user is found.

The OpenSpirit user with primary or secondary account that matches the account used to run the Tomcat or Jetty server must be granted the Administer OpenSpirit Runtime or the Impersonate OpenSpirit User right for authenticated access to work in TOWS. This gives the account running TOWS permission to access information about other OpenSpirit users and the ability to send events on event channels used for other OpenSpirit users.

Requests to the TOWS data service are restricted to the data sources and projects that the authenticated user has permission to access. Note, some OpenSpirit data source types restrict access by user (e.g. OpenWorks, Studio, and GeoFrame), and some do not restrict access by user.

The authenticated web user name to OpenSpirit user mapping is used for requests to access data, entities, and to send events. However, the actual data access is performed using OpenSpirit data connector processes that are running under the OpenSpirit user that is running your web application container. This means all sources of data that you want to make available in TOWS must be accessible by the OpenSpirit user that is running your web application container. The authenticated web user's identity is only used to test for project access permissions and to send events.

Behavior Without Authentication All requests to access data, entities, and to send events are handled by the OpenSpirit user that is running your web application container that TOWS is installed into if authentication has not been enabled.



16 | API Usage

API Usage Http request methods The TOWS services are exposed as a combination of HTTP GET and HTTP POST requests. GET requests are used when the request parameters are simple and the request parameter values are not large. POST requests are used when the request parameters are complex or large. For example, parameters passed to the /data/query request may contain many thousands of characters of SQL query string, query parameter values, coordinate system descriptions, etc. An HTTP POST request is therefore used to submit queries to the data service. The POST request parameters are passed in the body of the HTTP request rather than as URL parameters.

One exception to the convention of using POST for requests involving complex parameters are image requests. Some of the TOWS services provide requests that return image files (for example, the /entity/horizon3dimage request). These requests are made using a GET request rather than a POST request to allow direct display of images in the browser even though the request parameters may be somewhat complex or large.

JSON JSON formatted strings are used to represent the parameter values supplied in the body of POST requests. JSON is also used to represent the request response for GET and POST requests with the exception of image requests. Image requests return either a .PNG or .JPG image.

The TOWS API Reference Documentation describes the JSON schemas for all the request and response objects that appear in the TOWS API.

OpenSpirit Services The REST requests supported by the TOWS services are grouped into a set of services. Each service is described in the following sections of this guide.

/openspirit The openspirit service provides requests for information about the TOWS installation's configuration and the services it provides. This information can be used to determine the version of TOWS that is running and the version and location of the OpenSpirit services that TOWS was configured to use. The openspirit service can also be used to discover if TOWS was configured to use authentication.


API Usage | 17

/carto The TOWS carto service provides requests to discover predefined projected and geographic coordinate systems from the EPSG database hosted by the OpenSpirit runtime. Requests are also provided convert points between coordinate systems and to obtain ESRI WKT (Well Known Text) representations of coordinate systems.

/data The TOWS data service provides requests to discover data sources and projects available to the OpenSpirit runtime. The data service also provides a query request that can be used to execute SQL SELECT, INSERT, UPDATE, and DELETE queries against data sources and projects.


http://www.epsg.org/

18 | API Usage

/entity The TOWS entity service provides requests that given datakey strings, return an array of JSON objects having the commonly used properties for the requested entity type. The primary purpose of the entity service is to provide the information commonly needed to graphically display a set of entities or to display a set of entities in a selection list or a report.

Image Requests Some of the requests provided by the entity service return images. The image requests return either an image/png or image/jpg content type depending on the Accept header in the request. Seismic image requests return image/jpg by default if the content type is not specified in the request header. Horizon image requests return image/png by default if the content type is not specified in the request header. Horizon images default to PNG in order to use image transparency to represent null values in the horizon grid. Null values are not represented in seismic data, so the more compact JPEG format is used as the seismic image default.

Bulk Data Requests used for retrieving bulk data for seismic and 3D horizons return data with content type application/octet-stream. The response header x-ospmetadata returned with bulk data requests contains metadata describing the bytes returned by the request. This includes the bulk data sample type (BYTE, FLOAT, etc.), the byte order, and the axis orientation of the data along with other properties. JSON schemas are provided that describe the content of the response headers for each bulk data request.

Custom Entity Data Sources The most common source of entities is from OpenSpirit data sources, however TOWS also provides a mechanism to extend the entity service to provide access to data that is not available from the OpenSpirit data service. The Creating Custom Entity Data Sources


API Usage | 19

section of this guide describes how to extend the TOWS entity service to serve up entities from data sources that are not supported by the OpenSpirit data service.


20 | API Usage

/event The TOWS event service provides requests that can be used to send data selection events and GIS feature selection events. Events are sent using the OpenSpirit account used to run the TOWS services if TOWS is not configured to use authentication. Events are sent using the OpenSpirit user account that matches the name of the authenticated web user if TOWS is configured to use authentication.

Sending Data Selection Events Sending data selection events is quite simple. You just need to provide one or more datakey strings.

Note: only OpenSpirit datakeys are supported by this request. Datakey strings for custom entity data sources cannot be sent using this event.

Sending GIS Feature Events Sending GIS feature events is more involved than sending data selection events. The SendGISRequest JSON object used to send GIS features allows Polygon, LineString, and Point layers to be sent. Please see the Event Service Example for more information about creating a SendGISRequest object.


API Usage | 21

/metamodel The TOWS metamodel service provides requests to discover the details of data models supported by the OpenSpirit data service. This includes details of the OpenSpirit common model as well as details of the native data models supported by OpenSpirit data connectors.

/unit The TOWS unit service provides requests to discover predefined unit catalogs, unit measurements, units, and unit systems defined in the metadata repository database hosted by the OpenSpirit runtime. Requests are also provided convert values between units.


22 | API Usage


Example Web Application | 23

Example Web Application An example application is provided with the TOWS SDK. The example is written in JavaScript and makes use of the AngularJS JavaScript framework and user interface components. TOWS does not require you to use JavaScript or AngularJS to develop your web application. You are free to use any technology you like to make HTTP REST requests to the TOWS services. The example application can be run in any HTML5 compliant web browser capable of running AngularJS based applications.

The example application can be accessed using the link http://<host>:<port>/openspirit-sdk/Examples/WebAppExample. This link is click able if you are viewing the user guide from a live TOWS installation. The source code for the application is provided in the Examples/WebAppExample folder within the openspirit-sdk.war file. The JavaScript and HTML files for each tab in the example application is in its own sub-directory.

The example application is written using AngularJS components. It is not mandatory to understand AngularJS and components in order to use the example to understand how to issue TOWS service requests, but it will make reading the example code easier.


https://angularjs.org/

https://docs.angularjs.org/guide/component

24 | Example Web Application

The example application is composed as a set of tabs, each tab representing one or more of the TOWS services. The Home tab displays the base URL of the TOWS services that the openspirit-sdk.war file is installed into.

Unit Service Example Overview The unit service example defines a unit selector component used to select a unit catalog, unit measurement, and unit. The Unit panel displays a From unit selector component and a To unit selector component.

An arrow button between the unit selection components can be pressed to convert a value entered for the From unit selector to the unit chosen in the To unit selector. The To unit selector component is constrained to only offer measurements and units that can be converted from the unit selected in the From unit selector.

Carto Service Example Overview The carto example is similar to the unit example in that it presents a panel containing a From coordinate system selector and a To coordinate system selector.



The top section of each coordinate system selector contains a CRS Type option to indicate if a geographic system or a projected system is to be selected. Filters are provided below the CRS Type selection that enables filter values to be entered which will constrain the coordinate systems that appear in the Coordinate Reference System selection list. Be sure to click on the Apply button after entering filter values. The selection list will contain the names of several thousand coordinate systems if no filter values are applied.

The transform selection list will contain all of the transforms that can be used to transform between the selected coordinate system's datum and the WGS 84 datum. The transform list will be empty if the selected coordinate system has WGS 84 as its datum or if no datum transform to WGS 84 exists for the selected system.

Clicking on the arrow button between the From and To selectors will convert the X/Y or Latitude/Longitude values entered in the From selector to the coordinate system selected in the To selector.

Data and Metamodel Service Example Overview The data and metamodel example shows how a data source can be selected and queried and how the metamodel service can be used to obtain information about the entities and



attributes that can be queried. The example presents a project selection component on the left of the panel and a query construction component on the right side of the panel. The query result is displayed at the bottom of the panel.





Use the Select Project component to select the data source project that you would like to query. The Select model selector at the top of the Construct Query component can be used to choose between an OpenSpirit common model query and a native model query if the selected data source type supports native model access. Some data source types can only be queried using the OpenSpirit common model.

You can either directly type the query to be executed into the query text entry field, or you can click on the Select entity/attributes via metamodel service button to open a component that uses the TOWS metamodel service to select an entity and the entity attributes that you would like to query. An optional integer value can be entered in the Number of rows field to constrain the query to return a maximum number of rows.

You can use the OpenSpirit data selector query filter's view query feature to easily obtain a query string that can be copy/pasted into the example's query text entry field.

Click on the Run Query button to execute the query and display the result at the bottom of the panel.

A new data connector process may need to be started to run the query if a data connector process is not already running for the selected project. This will cause a delay in the query execution.

Event Service Example Overview The event service example shows how to use the TOWS event service to send OpenSpirit data selection events and OpenSpirit GIS feature selection events. The top of the example page indicates the OpenSpirit user that the events will be sent to. A count of the number of events that have been sent is also shown. The bottom section of the example page contains a tab used to send data selection events and a tab used to send GIS feature selection events.



A warning message is displayed on the event example page if TOWS has not been configured to use authentication. All events will be sent to the OpenSpirit user account that is being used to run the web application container that TOWS is running in if authentication is not being used.



Sending Data Selection Events Click on the Data Selection Event tab near the bottom of the page to display the panel that can be used to send data selection events. Obtain an OpenSpirit datakey from somewhere and paste it into the text entry field. You also can obtain datakeys by dragging one or more selected rows of data from the OpenSpirit data selector and drop the rows onto the datakey entry field.

Make sure you have an OpenSpirit enabled application that has data selection event listening enabled. You can use one of the OpenSpirit viewers, the OpenSpirit data selector, or any other application that can receive OpenSpirit data selection events. Click on the Send data selection event button to send the event.

Note, only one data key can be pasted into the text field of the example. However the /event/senddata request can accept an array of datakey strings.

Sending GIS Feature Selection Events Click on the GIS Event tab near the bottom of the page to display the panel that can be used to send GIS feature selection events. The GIS event panel displays a map from ESRI's public map service. You can pan and zoom the map to an area of the world that you want the GIS features to be located. You should pick an area that is visible from the OpenSpirit application you intend to use to receive the GIS event. You can use ESRI's ArcMap application with the OpenSpirit ArcGIS Extension, Schlumberger's Petrel application with



the OpenSpirit Adapter for Petrel, the OpenSpirit 3D viewer, or any other application that can receive OpenSpirit GIS feature selection events.

Once the map is position to the geographic area you would like to work in, select one or more of the Point, Linestring, or Polygon check boxes and click on the Add features button to generate some features that will be sent in the event. The generated features will be displayed on the map. Click on the Send GIS event button to create and send the generated features as an OpenSpirit GIS feature selection event.

Entity Service Example Overview The entity service example illustrates the use of the TOWS entity service to display tabular lists of entity properties. The example also shows how to access seismic and horizon images and bulk data.



Selecting Entities The TOWS entity service does not provide query capability. Entities are obtained by specifying one or more entity datakey in the request. Datakeys can be obtained from a TOWS data service query or from other sources such as the output of an OpenSpirit Scan Utility scan job. This entity service example application uses data service queries to obtain datakeys.

Click on the Select Data Source button to open the data source selection popup. Select the project that you would like to retrieve entities from. The number of entities that will be returned is constrained by the value entered in the Number of rows entry field. You should try to limit the number of entities returned so you don't overwhelm your browser. Click on

the right arrow icon next to the Number of rows entry field to execute the data service query to obtain data keys which are then used to request entities from the entity service. The entity retrieval may take some time if data connector processes need to be started or if the selected project contains a large amount of data and your number of rows limit is large.



The example also provides a Custom Data Keys window that can be used to copy/paste data key strings obtained through some other means. OpenSpirit datakeys or datakeys for entities supported by a custom entity data source can be pasted into the Custom Data Keys window. Click on the right arrow button to retrieve the entities after pasting one or more datakeys into the popup window. You will be responsible for obtaining the datakey strings from somewhere to use this feature.

Sending Data Selection Events The entity service example can be used to send data selection events to applications that have been enabled to receive OpenSpirit data selection events. Select one or more rows of

entities and click on the data selection event send icon . Data keys for the selected



entities will be sent to applications that are listening for data selection events. Note, only entities with OpenSpirit data keys will be sent. Entities coming from a custom entity data source will not be sent.

Viewing Entities in the Connect Sub-Surface Viewer

The Sub-Surface Viewer icon will be enabled if the TIBCO OpenSpirit Connect Sub-Surface Viewer is installed in your application container. Clicking on this icon will open the Sub-Surface Viewer, if it is not already open, and will send the selected entities to the viewer for display.

Image Requests You can use the example application to perform an image request using the Seismic 3d, Seismic 2d, Horizon 3d, or Non-seismic Horizon tab. Retrieve one or more entities using one of these tabs and scroll to the right to expose the Image column in the result table. Click on the ... in one of the image cells to open a popup that displays the image.

Various settings are provided to change the data range used to construct the image, the colors used to generate the image, and the image size in pixels. Click on the right arrow button to reconstruct the image using the new settings.



Bulk Data Requests Follow the same steps described above for viewing image data, but click on the ... in the Values column rather than the Image column. This will open a popup window that displays the bulk data values in a tabular form with settings that can be used to subset the data. You need to enter your sub setting options and click on the right arrow button to retrieve the bulk data values.


36 | Custom Entity Data Sources

Custom Entity Data Sources The TOWS entity service provides a mechanism to extend it to support requests for entities residing in data sources that are not supported by the OpenSpirit data service. This is done by creating a Java class that implements the com.tibco.openspirit.rest.entity.EntityProvider interface and registering it with TOWS. This interface is defined in the openspirit-rest-entity-1.0.0.jar file residing in the WEB-INF/lib folder in the openspirit.war file.

The TOWS entity service is used by the TIBCO OpenSpirit® Connect Sub-Surface Viewer to graphically display a variety of entity types. Custom entity data sources are sometimes created in order to display data in the viewers that cannot be accessed using one of the OpenSpirit data connector products.

The diagram shown below illustrates the role a TOWS custom entity provider plays in a typical web application workflow. A web application presents data coming from query requests to the TOWS data service along with data coming from some custom data source. The custom data source could be a relational database, a web service, files, or any other repository of data. The custom data source in this example can provide the web application with datakey strings that can be used to request data from a custom entity provider that has been registered with TOWS.

The web application user selects some data, some of which may be coming from the TOWS data service and some of which may be coming from the custom data source. The datakeys for the selected data is passed to the TIBCO OpenSpirit® Connect Sub-Surface Viewer for display. The Sub-Surface viewer uses the datakey strings to issue requests to the TOWS entity service for the information needed to graphically display the selected entities.


Custom Entity Data Sources | 37

The following pages of this guide describe the steps that must be followed to create and register a custom entity data source. The guide also introduces an example of a custom entity data source that is provided in the TOWS SDK.

Creating Custom Entity Data Sources Custom entity data sources are created by implementing a Java class that extends the com.tibco.openspirit.rest.entity.EntityProvider Java interface and registering the class with TOWS. Multiple custom entity data sources can be registered in a TOWS installation.

EntityProvider Class The class implementing the EntityProvider interface must be a public class with a public constructor that takes no arguments. The class must implement all of the methods defined in the EntityProvider interface. However, the EntityProvider can throw a com.tibco.openspirit.rest.entity.NotImplementedException as the implementation of any method that the provider does not wish to support. The com.tibco.openspirit.rest.entity.BadEntityRequestException exception should be thrown if any of the request arguments contain invalid values. The com.tibco.openspirit.rest.entity.ServiceException exception should be thrown if the request cannot be handled for an environmental reason, such as the database or file system that the entities are being read from is not available.

Registering an EntityProvider The Java class implementing the EntityProvider interface must be made available to TOWS by placing the class and any dependencies it may have in a Jar file residing in the TOWS WEB-INF/lib folder. The class must be registered in the entity-providers.xml file which is located in the TOWS WEB-INF folder. A Provider XML element should be added to the entity-providers.xml file specifying the name of the class and the datakey type string. An example of the entity-providers.xml file is shown below. The example registers the default OpenSpirit entity data source along with the LAS custom data source that is included as an example in the TOWS SDK.

<?xml version="1.0" encoding="UTF-8"?>

<EntityProviders>

<Provider keyType="OpenSpirit" className="com.tibco.openspirit.rest.entity.impl.OpenSpiritEntityProvider" />

<Provider keyType="LAS" className="com.mycorp.las.LasEntityProvider" />

</EntityProviders>


38 | Custom Entity Data Sources

Note, the XML attribute keyType="LAS" indicates that datakey strings that identify entities supplied by the custom entity provider are marked with a key type of LAS. The datakey string format is explained in the following section of this guide.

Entity Datakey Strings TOWS needs a way to know which entity provider to use to handle incoming entity service requests. This is done using entity datakey strings. The datakey strings for custom entity providers must be enclosed in an XML element that is named the same as the value of the keyType used to register the custom entity provider. The custom entity provider shown above in the entity-providers.xml file example used keyType="LAS" in its registration entry. This means that all datakey strings passed to the TOWS entity service that start with <LAS> and end with </LAS> will be passed to the LasEntityProvider class. The surrounding XML element must contain an XML attribute name en which indicates the type of entity identified by the key. For example, keys that identify a well log entity in the LAS example are surrounded by <LAS en="welllog"> ... </LAS>.

The entity names that can be used as the en XML attribute value in datakey strings are:

• wellbore

• welllog

• wellpick

• seismic2d

• seismic3d

• horizon2d

• horizon3d

• horizongrid

• fault

The default OpenSpiritEntityProvider class is registered with keyType="OpenSpirit". However, datakey strings for OpenSpirit common model entities are not surrounded with <OpenSpirit></OpenSpirit>, they appear as standard OpenSpirit datakey strings <key></key>. They are an exception to the keyType rule.

An XML parser is used parse the datakey strings passed to the entity service in order to determine the custom provider type and the entity type. This means the datakey string must be surrounded by an XML CDATA section if the datakey string contains any XML predefined entities (also referred to as XML metacharacters). The string can be in any format you choose. The LAS custom entity provider data source example provided with the TOWS SDK uses JSON to represent its entity datakey strings, but you are free to use any format you like.


https://www.w3.org/TR/REC-xml%23sec-cdata-sect

https://www.w3.org/TR/REC-xml%23sec-predefined-ent

Custom Entity Data Sources | 39

LAS Custom Entity Data Source Example An example custom entity data source is provided as an aid for developers wanting to create a custom entity data source. The example implements a custom entity data source that can respond to the TOWS entity service /entity/wellbore, /entity/wellbore/logs, and /entity/welllog requests by reading data from LAS files. The example is included in the Examples/las-entity-provider folder in the openspirit-sdk.war file.

The LAS example contains a Java class named LasEntityProvider that implements the Java com.tibco.openspirit.rest.entity.EntityProvider interface. The example also contains a class named LasDataKeyGenerator which given the path to a folder containing LAS files can create datakey strings that can be used to request entities from a TOWS installation that has been configured to use the LAS custom data source.

JSON formatted strings are used for the example's datakey strings. You are free to use any format you would like in your custom provider implementation. The LasDataKey class can be used to create datakey strings and it can be used to parse datakey strings used by the example.

The response object returned by most of the TOWS entity service requests contain an entity specific object (e.g. OspWellBore, OspWellLog, OspSeismic3D) each containing an explicit set of properties for that entity type. Note that the entity specific objects also contain a properties field that can be used to return an arbitrary set of name/value pairs. This enables your custom entities to expose attribute values that cannot be mapped into any of the explicit fields defined in the request object.

Javadoc for the LAS example classes can be found in the javadoc folder included with the example.


http://www.cwls.org/las/

Documents

OpenSpirit Web Services User's Guide · 2016. 9. 14. · JAX-RS specification (The Java API for RESTful Web Services) is used to define the services. The Jersey implementation of