TIBCO Spotfire® Server Web Services API · TIBCO® Spotfire® Server Web Service s API Samples Add the Sample Source Code The next step is to add the source code for the Web Services
Post on 03-Sep-2020
3 Views
Preview:
Transcript
TIBCO® Spotfire® Server Web Services API Samples
TIBCO Spotfire® Server Web Services API
API Samples
Software Release 7.8
February 2017
2
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
Known Issues ................................................................................................ 34
4
TIBCO® Spotfire® Server Web Services API Samples
Preface
Topics
Typographical Conventions, page 5
Connecting with TIBCO Resources, page 6
5
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
7
TIBCO® Spotfire® Server Web Services API Samples
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.
8
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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.
10
TIBCO® Spotfire® Server Web Services API Samples
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.
11
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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/)
15
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
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
TIBCO® Spotfire® Server Web Services API Samples
// 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
TIBCO® Spotfire® Server Web Services API Samples
/*****************************************************************/ /* 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
TIBCO® Spotfire® Server Web Services API Samples
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.
top related