tibco spotfire® server web services api...7 tibco® spotfire® server web service s api samples...

TIBCO® Spotfire® Server Web Services API Samples

TIBCO Spotfire® Server Web Services API

API Samples

Software Release 7.8

February 2017

2


Table of Contents Preface............................................................................................................... 4

Typographical Conventions ................................................................................ 5

Connecting with TIBCO Resources ...................................................................... 6

Introduction ........................................................................................................ 7

Understanding the Sample Code ............................................................................ 8

Configuring the Spotfire Server ............................................................................. 9

Enabling the Web Services API ........................................................................... 9

Granting Access to the Web Services ................................................................ 10

CSRF Protection of the Web Services ................................................................ 12

Compiling the .NET Sample Code ......................................................................... 13

Create a Visual Studio Project .......................................................................... 13

Add the Sample Source Code ........................................................................... 14

Creating the Service References ....................................................................... 15

Executing the .NET Sample Code ......................................................................... 18

Examining the .NET Sample Code ........................................................................ 19

Locating a User .............................................................................................. 19

Use of Domain Name ...................................................................................... 19

Use of Arrays ................................................................................................. 19

BASIC Authentication ...................................................................................... 20

CSRF Protection on Web Services ..................................................................... 21

Transport Message Size ................................................................................... 22

Compiling the Java Sample Code ......................................................................... 23

Create an Eclipse Project ................................................................................. 23

Add the Sample Source Code ........................................................................... 24

Creating the Service Proxies ............................................................................ 25

Executing the Java Sample Code ......................................................................... 28

Examining the Java Sample Code ........................................................................ 29

Locating a User .............................................................................................. 29

Use of Domain Name ...................................................................................... 29

Use of Generic List Class ................................................................................. 30

BASIC Authentication ...................................................................................... 30

CSRF Protection on Web Services ..................................................................... 31

Overriding the WSDL Binding ........................................................................... 32

3


Known Issues ................................................................................................ 34

4


Preface

Topics

Typographical Conventions, page 5

Connecting with TIBCO Resources, page 6

5


Typographical Conventions

The following typographical conventions are used in this manual.

General Typographical Conventions

Convention Use

code font Code font identifies commands, code examples, filenames,

pathnames, and output displayed in a command window. For

example:

Use MyCommand to start the foo process.

bold code font

Bold code font is used in the following ways:

In procedures, to indicate what a user types. For example:

Type admin.

In large code samples, to indicate the parts of the sample

that is of particular interest.

In command syntax, to indicate the default parameter for

a command. For example, if no parameter is specified,

MyCommand is enabled:

MyCommand [ enable | disable]

italic font Italic font is used in the following ways:

To indicate a document title. For example: See Concepts.

To introduce new terms For example: A portal page may

contain several portlets. Portlets are mini-applications that

run in a portal.

To indicate a variable in a command or code syntax that

you must replace. For example: MyCommand PathName

Key combinations

Key name separated by a plus sign indicate keys pressed

simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys

pressed one after the other. For example: Esc , Ctrl+Q.

The note icon indicates information that is of special interest

or importance, for example, an additional action required only

in certain circumstances.

The tip icon indicates an idea that could be useful, for

example, a way to apply the information provided in the

current section to achieve a specific result.

The warning icon indicates the potential for a damaging

situation, for example, data loss or corruption if certain steps

are taken or not taken.

6


Connecting with TIBCO Resources

How to Join TIBCO Community

TIBCO Community is an online destination for TIBCO customers, partners, and

resident experts, a place to share and access the collective experience of the

TIBCO community. TIBCO Community offers forums, blogs, and access to a

variety of resources. To register, go to https://community.tibco.com/.

How to Access All TIBCO Documentation

After you join TIBCO Community, you can access the documentation for all

supported product versions here:

http://docs.tibco.com/

How to Contact TIBCO Spotfire Support

For comments or problems with this manual or the software it addresses, please

contact TIBCO Spotfire 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.

If you have ideas for improvements and enhancements to the software, you

can visit the TIBCO Ideas Portal:

https://ideas.tibco.com/?project=TS

https://community.tibco.com/

http://docs.tibco.com/TibcoDoc

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

https://support.tibco.com/

https://ideas.tibco.com/?project=TS

7


Introduction

Spotfire Server 5.5 introduced a set of public Web Service APIs that allow

programmatic access to the Spotfire Server rather than having to use either the

Administration Console or Spotfire Analyst.

As of Spotfire Server 7.8, the current set of Spotfire Server Web Service APIs

contains the following services:

Information Model Service

Library Service

License Service

Security Service

Update Analysis Service

User Directory Service

For the Library Service and User Directory Service, sample code is provided

showing how to perform a subset of the available operations in both Java and

.NET code. This document is a companion to that sample code and explains:

How to understand the sample code

How to compile the sample code

How to run the compiled samples

The full Web Services API documentation can be found on the TIBCO

Documentation website in the Spotfire Server section.



https://docs.tibco.com/products/tibco-spotfire-server

8


Understanding the Sample Code

The sample code is divided into 3 major functional areas:

1. User and Group management tasks

- User and Group creation and deletion and Group membership

2. Library management tasks

- Folder creation and deletion and assignment of access rights

3. Library traversal operations

- Recursive traversal of the library and retrieval of item and folder

metadata

When run, the sample code presents a list of these three areas:

Please choose from the following samples...

1 - User creation / deletion and rights assignment

2 - Spotfire Library search / creation / deletion operations

3 - Spotfire Library traversal and item details

Press q to quit

The user chooses one and the sample code for that area executes:

Please choose from the following samples...

1 - User creation / deletion and rights assignment

2 - Spotfire Library search / creation / deletion operations

3 - Spotfire Library traversal and item details

Press q to quit

Option 1 - User creation / deletion and rights assignment

=========================================================

Searching for user 'myAdminUser'

...

Once completed, the user is returned to the list.

9


Configuring the Spotfire Server

There is some additional configuration required with a default Spotfire Server

installation before the Web Services API can be used.

The activities consist of:

Enabling the Web Services API

Granting a User the required permissions

Enabling CSRF Protection (optional)

Enabling the Web Services API

The Web Services API is disabled by default when the Spotfire Server is installed.

We must enable the API in order to access the WSDLs and execute any of the

Web Service operations.

To enable the Web Services the Spotfire Server configuration must be exported to

a file using either the GUI Configuration Tool or the config command line utility

(export-config).

Once the file is exported, one can use the command-line (config-web-service-api)

or edit the file directly. Directions for using the command-line are in the on-line

documentation for the Spotfire Server Web Services API. To edit the file, open

the configuration XML file in a text editor and locate the following lines:

<public-api>

<web-services>

<enabled>false</enabled>

</web-services>

</public-api>

Change the value of the <enabled> element to “true” and save the file. At this

point, one can import the configuration file back into Spotfire Server. Depending

upon the Spotfire Server’s restart policy, the Spotfire Server may have to be

manually restarted for this change to take effect. If there is more than one

Spotfire Server, each server will need to be restarted to get the new

configuration.

The Web Services API can now be accessed.

https://docs.tibco.com/pub/spotfire_server/7.8.0/doc/html/TIB_sfire_server_tsas_admin_help/GUID-3188EF2A-E7BD-481C-822B-7579B69B0DB9.html

https://docs.tibco.com/pub/spotfire_server/7.8.0/doc/html/TIB_sfire_server_tsas_admin_help/GUID-FA8614D9-CDD3-4C02-B62F-59E7074B15AB.html

10


Granting Access to the Web Services

Spotfire Server is installed and configured in a specific Authentication Mode.

Whatever mode is currently active for the Spotfire Server is also used to

authenticate and authorize calls to the Web Services API.

See the Spotfire Server Installation and Configuration manual for details of

different Authentication Modes. As noted in the next section, one can also enable

CSRF protection for the Web Services API.

Although the Web Services API supports all possible Spotfire Server

Authentication methods, the code samples are only written to work with

a Spotfire Server installed in BASIC Authentication mode.

If you are using a different authentication method, you will need to make

modifications to the sample code before it will work on your system.

Any user account used to call the Web Services must be added to the built-in API

User group. Only members of the API User group may download WSDLs and

perform Web Service operations. In order to run the code samples, the user

account to be used must be added to this group.

The steps below describe how to add the required group memberships to the

fictional Spotfire Administrator user “spotfireadmin”.

These steps can be done using the “Administration Manager” tool in Spotfire

Analyst or using the Spotfire Administration Web Console. These instructions use

the Spotfire Administration Web Console.

https://docs.tibco.com/products/tibco-spotfire-server

11


1. Open a Web Browser and open the Spotfire Server URL, as “spotfireadmin”

and click on “Users & Groups”

2. Locate the “spotfireadmin” user and click “Add” to edit the group memberships

3. Select the “API User” group and click Save

12


CSRF Protection of the Web Services

Starting with Spotfire Server 7.5, the Web Services API has built-in protection

against Cross-Site Request Forgery (CSRF) attacks. This CSRF protection is not

enabled by default. The sample code can connect to Web Services that have

CSRF protection enabled or disabled.

The sample code has a Boolean variable, called bCSRFEnabled, that can

be set to run (true) or not run (false) the CSRF specific code.

If one wants to enable CSRF protection, it is better to do it after one has obtained

the WSDL for developing the Web Services. The WSDL cannot be downloaded

when CSRF protection is enabled and the service discovery in Visual Studio and

Java cannot create the service stubs when CSRF protection is enabled.

To enable one needs to:

1. Export the Spotfire Server configuration to a file

2. Enable the CSRF protection using the command-line

3. Import the updated configuration into the database

4. Restart the Spotfire Server

These are the basic command-line commands one needs to run:

config export-config –-force

config config-csrf-protection –-public-web-services=true

config import-config –c “Enabled CSRF protection for public Web Services”

The on-line documentation has more details regarding the synchronizer token

pattern that the CSRF protection mechanism uses.

13


Compiling the .NET Sample Code

This consists of the following steps:

Creating a Visual Studio Project

Adding the sample source code

Creating the Service References from the Spotfire Server WSDLs

Create a Visual Studio Project

The first step is to create a project in Visual Studio. This example was done using

Visual Studio 2013.

1. Create a new Console Application called “TSSAPISampleCode” as shown

below:

14


Add the Sample Source Code

The next step is to add the source code for the Web Services API samples to the

project.

2. Right click the “Program.cs” entry in the Project Explorer window, and rename

it to “TSSAPISampleCode.cs”.

3. Paste the contents of the downloaded “TSSAPISampleCode.cs” sample code

file into the “TSSAPISampleCode.cs” file in the Visual Studio project.

Ignore any compilation errors at this point

4. To support the CSRF protection, some other code is needed to manage the

cookies. Right-click on the TSSAPISampleCode project in the Solution

Explorer and select Add -> Existing Item. Browse to where you have

downloaded the code and select the CookieManagerBehaviorExtension.cs,

CookieManagerEndpointBehavior.cs, and CookieManagerMessageInspector.cs

files. Click Add button. (Note this code is based on a blog post titled

"Managing shared cookies in WCF" by Enrico Campidoglio -

http://megakemp.com/2009/02/06/managing-shared-cookies-in-wcf/)

http://megakemp.com/2009/02/06/managing-shared-cookies-in-wcf/

15


5. The CookieManagerBehaviorExtension.cs file requires another assembly

reference. In the Solution Explorer, right-click the “References” and select

Add Reference. In the Framework Assemblies list, scroll down and select

“System.Configuration” making sure to check the box, then click OK.

Creating the Service References

The last step is to read the Spotfire Server WSDLs and create the Service

References.

6. Within the Solution Explorer, right click on the “TSSAPISampleCode” Project

and select Add -> “Service Reference”

The path to the User Directory Service WSDL file is of the form:

http://<server>:<port>/spotfire/ws/pub/UserDirectoryService?wsdl

Enter the correct path for your server and click “Go”. You will be prompted

multiple times to authenticate yourself as Visual Studio retrieves the

component parts of the WSDL file. Eventually the dialog will update to show

the retrieved service.

16


7. Enter the Namespace as “UserDirectoryService” and click OK.

In this example, our Spotfire Server is setup using BASIC Authentication

against the Spotfire Server database.

Depending on how your Spotfire Server is configured you may have to

run the WSDL retrieval process as a particular user or alter the

authentication method on the Spotfire Server while you retrieve the

WSDL files.

Note that if CSRF protection for the Web Services API is enabled at this

point, the Add Service Reference will fail with an HTTP 403 Forbidden

error.

8. Repeat steps 4 and 5 above to create a Service Reference for the Library

Service called “LibraryService”.

The path to the Library Service WSDL file is of the form:

http://<server>:<port>/spotfire/ws/pub/LibraryService?wsdl

17


9. The files generated by Visual Studio have extra namespace information that

we don’t want. We need to edit these generated files before we can use them

in our project.

In the Solution Explorer window, click on the “Show all Files” toolbar button

and expand the tree under the UserDirectoryService Service Reference until

you locate the “Reference.cs” file.

Open the Reference.cs file in the editor and remove all occurrences of the

string “TSSAPISampleCode.UserDirectoryService.” (note the trailing period).

Save and close the file.

Expand the tree under the LibraryService Service Reference until you locate

the “Reference.cs” file.

Open the Reference.cs file in the editor and remove all occurrences of the

string “TSSAPISampleCode.LibraryService.” (note the trailing period). Save

and close the file.

10. As noted earlier, the sample code has a Boolean variable, called bCSRFEnabled,

that can be set to run (true) or not run (false) the CSRF protection specific code. Please set bCSRFEnabled correctly before compiling and running the

code.

If the CSRF protection is enabled on the Web Services API, then bCSRFEnabled

must be set to true. If CSRF protection is disabled on the Web Services API, then bCSRFEnabled can be set to true or false.

If CSRF protection is not needed, then some code can be removed and the

extra code files added in Step 4 are not needed.

At this point the project should compile successfully.

18


Executing the .NET Sample Code

The sample code is written to accept parameters on the command line as follows:

Usage: TSSAPISampleCode [options]

where options are:

-server <server> - Spotfire Server Address

-port <port> - Spotfire Server Port

-user <user name> - Spotfire Server User Name

-password <password> - Spotfire Server Password

-debug <debug> - Set to true to enable debug output

For example:

TSSAPISampleCode -server spotfiredemo –port 9090 -user spotfireadmin -password spotfireadmin -debug true

19


Examining the .NET Sample Code

The following sections look inside the sample code to point out areas of interest

for programmers using the samples as a basis for their own code.

Locating a User

There are two ways of locating a User using the Web Services API:

getUserByName() – takes an actual User Name and returns at most 1 result

searchUsers() – take a search expression and returns 0, 1 or many results

Within the doUserSample() function, the sample code demonstrates using one or

the other of these methods. Which method is used is determined by the value of the Boolean variable bDoUserSearch in the doUserSample() function.

To use the searchUsers() method, set the bDoUserSearch variable to true:

static void doUserSample () { Boolean bDoUserSearch = true; ...

To use the getUserByName() method, set the bDoUserSearch variable to false.

Use of Domain Name

When working with Users and Groups, these objects have two members:

name – the name of the User or Group

domainName – the Spotfire Domain that the item belongs to

In the sample code the Domain Name is defaulted to “SPOTFIRE”. This is the

default internal Domain created at installation.

For further information on the use of Domains, see the Spotfire Server Installation

and Configuration Manual.

Use of Arrays

20


Wherever the Web Services API takes as input or returns as output data that

describes multiple objects, arrays are used.

So for example, the call to delete a User can delete multiple users in one go. To

call it, an array is created containing the User to be deleted and this is passed to

the actual API call.

UserDirectoryService.PrincipalName[] arUserNamesToDelete = new UserDirectoryService.PrincipalName[] { myAdminUser.principalName }; myUserDirectoryServiceClient.removePrincipals ( arUserNamesToDelete );

Similarly, when retrieving the child items of a Library Folder, the result is an array

of items.

LibraryItem[] arChildItems = null; arChildItems = myLibraryServiceClient.getChildItems ( thisLibraryItem.id );

The returned array should never be null, but it may be empty if no items were

returned.

BASIC Authentication

The sample code is written to work with a Spotfire Server configured to use the

BASIC Authentication method, which is the installation default.

BasicHttpBinding HTTPBinding = new BasicHttpBinding (); HTTPBinding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly; HTTPBinding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic; EndpointAddress DirectoryEndpoint = new EndpointAddress ( "http://"+ server + ":" + port + strUserDirectoryServiceEndpoint ); UserDirectoryServiceClient myUserDirectoryServiceClient = new UserDirectoryServiceClient ( HTTPBinding, DirectoryEndpoint ); myUserDirectoryServiceClient.ClientCredentials.UserName.UserName = user; myUserDirectoryServiceClient.ClientCredentials.UserName.Password = password;

21


CSRF Protection on Web Services

The sample code is written to work with a Spotfire Server configured with the

CSRF protection enabled or disabled. The CSRF protection is disabled by default

on Spotfire Server.

As mentioned earlier, the other code files, CookieManagerBehavorExtension.cs,

CookieManagerEndpointBehavior.cs, and CookieManagerMessageInspector.cs, are

needed in order to support pulling the CSRF cookie out of the HTTP response and

then adding it to the HTTP Header in the request. Most of this work is done in the

CookieManagerMessageInspector.cs.

In the sample code itself, the important code lines are initializing the variables for

CSRF:

// is CSRF Enabled on the Server or not // used to bypass code that is not needed static Boolean bCSRFEnabled = true; // Cookie manager only needed when CSRF is Enabled static WcfCookieManager.CookieManagerEndpointBehavior wcfCookieBehavior = new WcfCookieManager.CookieManagerEndpointBehavior();

Sample code in which the initial cookies are obtained to support the CSRF

protection:

/****************************************************************************/ /* If CSRF Enabled, Do initial call to get authentication tokens */ /****************************************************************************/ if (bCSRFEnabled) { // add cookie support to handle XSRF myUserDirectoryServiceClient.Endpoint.Behaviors.Add(wcfCookieBehavior); // get initial XSRF and JSESSIONID token and set into Web Service cookies wcfCookieBehavior.SetCookieInfo(getInitialCookies ("http://" + server + ":" + port + strSpotfireServerBase)); }

This code adds the cookie behaviour class to the client endpoint. This allows the

HTTP requests and responses to be captured. The second line of code makes an

initial unauthenticated call to the Spotfire Server in order to get the CSRF token.

22


Transport Message Size

By default, the BasicHTTPBinding object used in the creation of the Web Services

clients has a default maximum received message size of 64K bytes, a Send

Timeout of 1 minute and a receive Timeout of 10 minutes.

When using the LibraryService API methods, the response messages can become

quite large and may exceed the default buffer size allocated by Visual Studio for

Web Services messages.

In addition, the API methods may take longer to execute due to the amount of

information being retrieved and encoded for return to the caller. In such cases

the default send and receive timeouts may be exceeded.

In order to prevent this, the doLibrarySample2 () function uses the alternate

BasicHTTPBinding constructor in the .NET API to increase the default buffer size

and override the send and receive message timeouts.

TimeSpan Timeout = new TimeSpan ( 0, 10, 0 ); BasicHttpBinding HTTPBinding = new BasicHttpBinding () { MaxReceivedMessageSize = 131072000, ReceiveTimeout=Timeout, SendTimeout=Timeout };

The exact values may have to be adjusted through experience.

23


Compiling the Java Sample Code

This consists of the following steps:

Creating an Eclipse Project

Adding the sample source code

Creating the Service Proxies from the Spotfire Server WSDLs

Create an Eclipse Project

The first step is to create a project in Eclipse.

1. Create a new Eclipse Java Project called “TSSAPISampleCode” as shown

below:

Select “Finish” to create the Project.

24


Add the Sample Source Code

The next step is to add the source code for the Web Services API samples to the

project.

2. Expand the Project node, right click the “src” node and select New ->

Package. Create a package called “com.tibco.spotfire.TSSAPISamples” as

shown:

Repeat the above steps to create two more packages called “com.tibco.spotfire.TSSUserDirectoryService” and

“com.tibco.spotfire.TSSLibraryService”.

3. Right click on the “com.tibco.spotfire.TSSAPISamples” package and select

New -> Class. Enter the class name as “TSSAPISampleCode” and click “Finish”.

Open the newly created “TSSAPISampleCode.java” file in the Eclipse project and

delete the entire contents.

Paste the contents of the downloaded “TSSAPISampleCode.java” sample code

file into the “TSSAPISampleCode.java” file in the Eclipse project. Save the file.

Ignore any compilation errors at this point

4. To support the CSRF protection, some other code is needed to manage the

CSRF headers and cookies. Right-click on the “com.tibco.spotfire.TSSAPISamples” package and select Import. For the

import source, select General -> File System and click “Next”.

Browse to the downloaded code and select the “TSSWSAPIHandler.java” file as

seen below and click “Finish”.

25


This file contains extra handling of the underlying Web Services messages in

order to pull out the CSRF cookie and add to the HTTP headers.

Creating the Service Proxies

The last step is to read the Spotfire Server WSDLs and create the Service Proxies.

5. Open a web browser and navigate to the User Directory Service WSDL file.

The path to the User Directory Service WSDL file is of the form:

http://<server>:<port>/spotfire/ws/pub/UserDirectoryService?wsdl

The web browser will prompt for authentication

Once you have the WSDL file displayed in the browser, save the contents to a

file on the hard drive.

In order to open the WSDL file in the browser, you must authenticate as

a user that is a member of the “API User” group.

For this example it is assumed that the Spotfire Server is setup using

BASIC Authentication against the Spotfire Server database. This is the

default option.

Depending on how your Spotfire Server is configured you may have to

run the WSDL retrieval process as a particular user or alter the

authentication method on the Spotfire Server while you retrieve the

26


WSDL files.

In order to download the WSDL files, the CSRF protection on the Web

Services must be disabled. The CSRF protection can be enabled after

one has downloaded the WSDL files for the services. One could also

have a Development environment with the CSRF protection disabled and

then have a Production environment with the CSRF protection enabled.

If the Web Services code will be run in an environment with the CSRF

protection enabled, then the WSDL files saved for the

UserDirectoryService and the LibraryService will need to be accessible at

runtime.

6. Use the Java wsimport utility to create Java Proxy classes from the WSDL file.

wsimport -s <path to java project src folder> -p com.tibco.spotfire.TSSUserDirectoryService <path to downloaded User Directory Service WSDL file>

For Example,

C:\tibco\tss\7.7.0\jdk\bin\wsimport -s E:\Workspace\TSSAPISampleCode\src -p com.tibco.spotfire.TSSUserDirectoryService E:\Workspace\UserDirectoryService.wsdl

The wsimport utility is located in the “bin” folder of a Java JDK

installation.

7. Repeat step 4 to save the Library Service WSDL to a temporary folder on the

hard drive.

The path to the Library Service WSDL file is of the form:

http://<server>:<port>/spotfire/ws/pub/LibraryService?wsdl

8. Use the Java wsimport utility to create Java Proxy classes from the WSDL file.

wsimport -s <path to Eclipse project src folder> -p com.tibco.spotfire.TSSLibraryService <path to the downloaded Library Service WSDL file>

For Example,

C:\tibco\tss\7.7.0\jdk\bin\wsimport -s E:\Workspace\TSSAPISampleCode\src -p com.tibco.spotfire.TSSLibraryService E:\Workspace\LibraryService.wsdl

27


This will create the Java Proxy classes under the Java Packages created in

Step 4.

9. In the Eclipse IDE, refresh the contents of the “com.tibco.spotfire.TSSUserDirectoryService” and

“com.tibco.spotfire.TSSLibraryService” Java Packages. One can refresh the

source tree by right-clicking packages and selecting “Refresh” from the menu.

The Project should now compile successfully.

28


Executing the Java Sample Code

The sample code is written to accept parameters on the command line as follows:

Usage: TSSAPISampleCode [options]

where options are:

-server <server> - Spotfire Server Address

-port <port> - Spotfire Server Port

-user <user name> - Spotfire Server User Name

-password <password> - Spotfire Server Password

-debug <debug> - Set to true to enable debug output

For example:

java –cp ... com.tibco.spotfire.TSSAPISamples.TSSAPISampleCode -server spotfiredemo –port 9090 -user spotfireadmin -password spotfireadmin -debug true

The actual classpath will depend on the setup of the system running the sample

code. However at least the following must be present on the classpath:

The path to the location of the compiled sample code or a jar file containing

the compiled sample code

The Axis client libraries

29


Examining the Java Sample Code

The following sections look inside the sample code to point out areas of interest

for programmers using the samples as a basis for their own code.

Locating a User

There are two ways of locating a User using the Web Services API:

getUserByName() – takes an actual User Name and returns at most 1 result

searchUsers() – take a search expression and returns 0, 1 or many results

Within the doUserSample() function, the sample code demonstrates using one or

the other of these methods. Which method is used is determined by the value of the boolean variable bDoUserSearch in the doUserSample() function.

To use the searchUsers() method, set the bDoUserSearch variable to true:

static void doUserSample () { boolean bDoUserSearch = true; ...

To use the getUserByName() method, set the bDoUserSearch variable to false.

Use of Domain Name

When working with Users and Groups, these objects have two members:

name – the name of the User or Group

domainName – the Spotfire Domain that the item belongs to

In the sample code the Domain Name is defaulted to “SPOTFIRE”. This is the

default internal Domain created at installation.

For further information on the use of Domains, see the Spotfire Server Installation

and Configuration Manual.

30


Use of Generic List Class

Wherever the Web Services API takes as input or returns as output data that

describes multiple objects, Java Generic List objects are used.

However, as the List class is an interface, a class that implements this interface

must be used. In the sample code, the ArrayList class is used.

So for example, the call to delete a User can delete multiple users in one go. To

call it, an ArrayList is created containing the User to be deleted and this is passed

to the actual API call.

ArrayList<com.tibco.spotfire.TSSUserDirectoryService.PrincipalName> lstUserNamesToDelete = new ArrayList<com.tibco.spotfire.TSSUserDirectoryService.PrincipalName> (); lstUserNamesToDelete.add ( myAdminUser.getPrincipalName() ); myUserDirectoryServiceClient.removePrincipals ( lstUserNamesToDelete );

However when API functions return collections, they simply return the List

interface. So when retrieving the child items of a Library Folder, the result is as

follows:

List<LibraryItem> lstChildItems = null; lstChildItems = myLibraryServiceClient.getChildItems(thisLibraryItem.getId());

The returned List object should never be null, but it may be empty if no items

were returned.

BASIC Authentication

The sample code is written to work with a Spotfire Server configured to use the

BASIC Authentication method, which is the installation default.

This is accomplished by overriding the Authenticator object for all HTTP

authentication requests and routing all requests for Username and Password to a

function that uses the parameters supplied by the user at runtime.

Authenticator myAuthenticator = new Authenticator () { @Override protected PasswordAuthentication getPasswordAuthentication () { return new PasswordAuthentication ( user, password.toCharArray()); } }; Authenticator.setDefault ( myAuthenticator );

31


This mechanism should work for all challenge/response protocols such as

NTLM.

However the code has not been tested in this configuration.

CSRF Protection on Web Services

The sample code is written to work with a Spotfire Server configured with the

CSRF protection enabled or disabled. The CSRF protection is disabled by default

on Spotfire Server.

As mentioned earlier, the additional code file, TSSWSAPIHandler.java, is needed

in order to support pulling the CSRF token out of the HTTP response and then

adding it to the HTTP Header in the request.

In the sample code itself, the bCSRFEnabled variable determines if the code for

CSRF protection will be run or not:

// is CSRF Enabled on the Server or not // used to bypass code that is not needed static Boolean bCSRFEnabled = true;

The first difference is that if CSRF protection is enabled, then the WSDL

information must be obtained from a local file resource rather than obtaining it via

an HTTP call.

/***********************************************************************/ /* If CSRF Enabled, then need to get WSDL differently */ /***********************************************************************/ if (bCSRFEnabled) { // if CSRF is Enabled, then have to get WSDL locally userdirectory_service = new UserDirectoryService_Service( TSSAPISampleCode.class.getResource("UserDirectoryService.wsdl"), new QName ( annotation.targetNamespace(), annotation.name() ) ); } else // CSRF is disabled can get WSDL from website { userdirectory_service = new UserDirectoryService_Service( new URL ( "http://" + server + ":" + port + strUserDirectoryServiceEndpoint + "?wsdl"), new QName ( annotation.targetNamespace(), annotation.name())); }

The main code to configure the TSSWSAPIHandler is in a function called

configureServiceSession that handles configuring the request context and then

setting the handler:

32


// if CSRF Enabled, then need to getInitialCookies and configure Handler if (bCSRFEnabled) { // Configure Message Handler to handle setting cookie and XSRF-TOKEN TSSWSAPIHandler tssWSAPIHandler = new TSSWSAPIHandler(); tssWSAPIHandler.setCookieInfo(getInitialCookies("http://" + server + ":" + port + strSpotfireServerBase)); List<Handler> handlerChain = new ArrayList<Handler>(); handlerChain.add(tssWSAPIHandler); Binding bindObj = wsdlProvider.getBinding(); bindObj.setHandlerChain(handlerChain); }

This code adds a handler for processing the HTTP requests and responses behind

the scenes. The handler takes the CSRF and JSESSIONID cookies and then adds

them to the response. The CSRF token has to be added to the HTTP header in

order to avoid the HTTP 403 forbidden error.

Overriding the WSDL Binding

The classes generated by the Web Services Client wizard have the binding path

from the original WSDL hard coded into them.

public class UserDirectoryService_Service extends Service { private final static URL USERDIRECTORYSERVICE_WSDL_LOCATION; private final static WebServiceException USERDIRECTORYSERVICE_EXCEPTION; ....... static { URL url = null; WebServiceException e = null; try { url = new URL("http://localhost:8077/spotfire/ws/pub/UserDirectoryService?wsdl"); } catch (MalformedURLException ex) { e = new WebServiceException(ex); } USERDIRECTORYSERVICE_WSDL_LOCATION = url; USERDIRECTORYSERVICE_EXCEPTION = e; } ........

In order to override this default, it is necessary to use the alternate form of the UserDirectoryService_Service constructor and pass in the WSDL location on the

server being accessed, and the Service QNAME.

// // Create the User Directory Service instance // WebServiceClient annotation = UserDirectoryService_Service.class.getAnnotation(WebServiceClient.class); UserDirectoryService_Service userdirectory_service = null;

33


/*****************************************************************/ /* If CSRF Enabled, then need to get WSDL differently */ /*****************************************************************/ if (bCSRFEnabled) { // if CSRF is Enabled, then have to get WSDL locally userdirectory_service = new UserDirectoryService_Service( TSSAPISampleCode.class.getResource("UserDirectoryService.wsdl"), new QName ( annotation.targetNamespace(), annotation.name() ) ); } else // CSRF is disabled can get WSDL from website { userdirectory_service = new UserDirectoryService_Service( new URL ( "http://" + server + ":" + port + strUserDirectoryServiceEndpoint + "?wsdl" ), new QName ( annotation.targetNamespace(), annotation.name() ) ); } UserDirectoryService myUserDirectoryServiceClient = userdirectory_service.getUserDirectoryServicePort (); configureServiceSession((BindingProvider)myUserDirectoryServiceClient, strUserDirectoryServiceEndpoint);

One can also set the ENDPOINT_ADDRESS_PROPERTY to set the service URL:

requestContext.put( BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://" + server + ":" + port + strServiceURL );

The above code is only required if the JAX-WS libraries are used.

However other Web Services client libraries have similar behaviour, so a

similar workaround may be necessary.

Also note as mentioned in the CSRF section above, if CSRF protection is

enabled, then the WSDL file must be read locally.

34


Known Issues

The table in this section lists known issues in this release.

Key Summary/Workaround

WSIMPORT-

WARN-1

Summary: When using either the Java wsimport utility or the

Eclipse Web Services Client Wizard to generate Java Proxy Classes

from the UserDirectoryService WSDL file, the following warning

message maybe produced multiple times:

[WARNING] src-resolve: Cannot resolve the name 'ns1:GUID' to a(n) 'type definition' component.

line 27 of file:/<path>/UserDirectoryService.wsdl#types?schema1

Workaround: None required. Despite the Warning messages,

the Java Proxy classes are successfully created and function as

required.

WSIMPORT-

WARN-2

Summary: When using either the Java wsimport utility or the

Eclipse Web Services Client Wizard to generate Java Proxy Classes

from the LibraryService WSDL file, the following warning

messages may be produced multiple times:

[WARNING] src-resolve: Cannot resolve the name 'ns1:GUID' to a(n) 'type definition' component.

line 16 of file:/<path>/LibraryService.wsdl#types?schema1

[WARNING] src-resolve: Cannot resolve the name 'ns2:UserName' to a(n) 'type definition' component.

line 279 of file:/<path>/LibraryService.wsdl#types?schema2

Workaround: None required. Despite the Warning messages,

the Java Proxy classes are successfully created and function as

required.

tibco spotfire® server web services api...7 tibco® spotfire® server web service s api samples...

Documents