a
Setting the HTTP Service Functions
An HTTP Service Function defines how to make a service call using an HTTP request. The key parts in setting up an HTTP Service are defining how to construct the URL and describing what to do with the response.
HTTP Service functions can also be configured as to how they will respond when the client is Offline.
From the Application Manager do one of the following:
Click on the New
HTTP service button in the toolbar 
.
Click on the Edit|New HTTP service menu item.
Right-click on the Services node in the Application Explorer window and select New HTTP service in the context menu.
A Service Function is added to the list of Services with the default name of HTTPSERVICE1.
The following Service details window will open:
In the Service name field, enter the name of your new Service Function.
On the request tab enter
the base URL.
For example: if you are using Altio
DB Manager this will be: ${db.server.protocol}://${db.server.name}:${db.server.port}/${db.server.path}com.altio.altiodb.AltioDB.
Please note: The parameters indicated by ${} will be substituted when the service is called, and will end up as something like: http://myserver:8080/servlet/altio/com.altio.altiodb.AltioDB. In this case the URL specifies the name of a servlet to call.
Enter any arguments
to append to the URL. These can be specified both in the URL argument,
and in the parameter list.
For example, the Altio DB Manager
accepts three arguments, APPID,
ACTION and TARGET.
These can be specified:
in the URL argument: APPID=ros&ACTION=GET&TARGET=/FOR_SALE, or
as three items in the parameter mapping list:
The parameter mapping
list has the advantage of supporting parameter substitution, so the following
settings provide the equivalent of using the URL argument. The full URL
that will be constructed in this case is:
http://myserver:8080/servlet/altio/com.altio.altiodb.AltioD&APPID=ros&ACTION=GET&TARGET=/STOCKS.
Select the Test tab and click on the Test button. This will test the Service Function, and provide feedback on whether the Service Function succeeded or not.
For more details on parameter substitution see property references. For details on other HTTP Service configuration options see below.
The Request tab specifies how the HTTP request is made when this Service is used.
Parameters can be passed from the Client, or application-specific parameters can be used. Client parameters will often involve the values of controls on windows. In this case you can use the Service Function Validation feature in the Designer to help you. Parameters mainly use Property References, but can also use plain text strings. The name of each parameter to be passed to the application server must be unique.
If a service function is used by a Datapool, then ${datapool.timestamp} can be used to pass the Datapool's timestamp. See What Are Datapools? for more information.
In the URL field enter the base URL to which the parameter names and values will be added. This can use the property values ${db.server.protocol}, ${db.server.name}, ${db.server.port} and ${db.server.path}, which will be substituted with the property values defined in the Server configuration.
From the Method drop-down menu choose the HTTP Method to be used when the Altio Presentation Server connects to the URL. Choose one of the following:
GET: use this method for less than 256 bytes.
POST: use this method for all the other sizes.
AUTO: the size of the parameter will determine automatically which method to use.
From the Encoding drop-down menu choose the encoding for parameters sent to the service. The latest HTTP specification requires UTF-8 to be used for parameters, but many older applications use other encodings. Set this to the encoding used by the backend to communicate with legacy applications. If the encoding you want is not one of the common ones in the drop-down list, you can type in the name of any encoding recognized by Java. The default encoding is UTF-8.
Tick the Make Multiple Calls option if you want that an HTTP request is made for each selected element. When a service call is made from a control that supports multiple selection (such as a list box) this flag controls how the request is forwarded. If Make multiple calls is not ticked then a single HTTP request is made for all the selected elements. The ${request.x} parameter can be used in the service definition to forward information on all the selected elements. For services that are not made from a control using multiple selection, this setting is ignored.
Tick the Block Arguments option if you want the URL argument to be interpreted as a single block instead of a series of name-value pairs. If selected, the Parameter Mapping list of name value pairs is changed to a URL Argument text box for entering a single block argument, for example XML. Default is N. Tick the Encode block argument option if you want the argument to be URL encoding as a single block before being send to the backend.
When invoking a HTTP Service that returns Set-Cookie or Set-Cookie2 header, Presentation Server saves the Cookie information so that when subsequent calls to services of same domain and path, this cookie information can be sent back. From the Server side cookie scope drop-down menu choose how the Presentation Server stores the cookie information and how cookie information will be shared among services. Choose one of the following option:
Session: Cookie is stored per HTTP Session and is shared among all services with SESSION cookie scope within same HTTP session.
Application: Cookie is stored per Altio Application and is shared among all services with APP cookie scope in the same application.
Presentation Server: Cookie is stored at Presentation Server and is shared among all services with PS cookie scope.
For more information: see Server Side Cookie Handling.
Tick the Send client cookie option if you want the Presentation Server to pass on cookie(s) from client browser to backend service.
In the Max # of attempts field, enter how many times the Presentation Server will have to try to connect if an exception is caught when the service is trying to connect or while it is connected to the specified URL . By default the attempts are set to 10 and minimum is 1.
If the Block
arguments option is not selected you can add a parameter in the
Parameter mapping box. These options
are used to send data along with the Service Function. To add a parameter
in the Parameter mapping box:
Click on the Add button.
Scroll down the list and add the new parameter with its Name and Value
in the list itself.
To delete a parameter from the Parameter
mapping, select it and click on the Delete
button.
Client parameters can be referred to using ${client.XXX}
where is an attribute sent from the client. The current user can be referred
to use ${connection.user}.
For more information: See property references for a full list of properties.
If the Block arguments option is selected you can enter an argument in the Argument box. An argument is sent without parsing into name value pairs. The argument will be URL encoded as a single block before being sent to the backend. You can use property references anywhere within the block. This permits, for example, a block of XML to be sent with attributes determined by input from the client.
The Response tab is used to define what type of data to expect from the service function, and optionally any extra processing that should be done to the data returned.
Specifies the type of document the Altio Presentation Server expects back from the application server. Can be set to XML, TXT, IMG (image) or EMPTY. If you want to return data to the Client, it must be an XML document. The TXT setting can be used to validate that the service function has completed successfully; if you don't want data to be returned you can use this setting. This setting is required.
Please note: This only applies to XML Service Functions.
Check this box if you want the Timestamp to be extracted from a customized location. If this option is selected you can set the Element and Attribute for locating timestamp information. By default Timestamp are extracted from a Timestamp Attribute on the root element of the XML returned by the Service.
Please note: This option is useful when the return data doesn't contain Timestamp information. However, if you use MASTER-MASTER cluster configuration, data might be lost in failover situation, because the timestamp value for a data block can be different on two Presentation Servers.
Please note: APS uses Java currentTimeMillis() to set the timestamp. Although its precision is down to 1 ms, the problem is that default timing systems on the native platforms are, in general, of low resolution. The currentTimeMillis is updated every 10ms ~ 16 ms. Therefore it is possible that 2 updates arrive in order but end up in the same millisecond.
Check this box if you want the Presentation Server to use system clock for the Timestamp value.
Set this field to an XPath statement pointing to the element containing Timestamp information. By default the Presentation Server continues to find Timestamp information from root element. If more than one element matches, only the first element is used.
Specify the attribute name containing the Timestamp info or TEXT() to indicate that the element's text contains the timestamp. By default the Presentation Server finds Timestamp information from Timestamp default attribute.
Specify whether the Timestamp field is to be read as a Date/Time or as an Integer. By default the Type is set to Integer.
Specify the Format used to parse the Timestamp from the specified Element and Attribute. For a Date/Time this should be a format recognized by java.text.SimpleDateFormat. For an Integer this should be a format recognized by java.text.DecimalFormat. By default if the Type is set to Integer then the Timestamp Attribute is read as an Integer.
Please note: The XSL file could potentially add or remove Elements, Attributes, change names of Elements or Attributes. Using this feature requires that a JAXP compliant XSLT library is available on the servlet engine's CLASSPATH, for example Xalan, Apache's open source XSLT library (xalan.jar).
Place your XSL file in the XSL sub-directory (under the Application root directory) as the Transformation XSL file drop-down menu displays only the XSL files in that directory.
Specify the XSL file you want to use to transform return XML data before it is sent to the client.
Check this box if you want this service to create a new transformer instance every time it does the transformation. By default this option is set to false.
The Acknowledgment tab is used to define how the success or failure of a Service Function is determined and how it is then communicated to the client. The Altio Presentation Server can determine the success of a particular Service Function call by either the response header or from the response body.
These messages are displayed by the AltioLive client in a default window. This window uses the caption defined in the Application View Properties. On the client it is possible to configure separate windows to display while the service function is being processed and when it concludes. Use the action rule Server request to configure these.
From the Source drop-down menu, choose the Source of acknowledgement string (in which part of the document to search). Choose one of the following:
RESPONSE: the Altio Presentation Server searches for a response message defined on the application.
HEADER: the Altio Presentation Server searches for a header parameter named X-Altio-Status. This should be set by the back-end to 0 to indicate success, and to 1 to indicate failure.
NONE: if there is no acknowledgement required. The success or the failure returned from the service call will not be passed on to the user.
If you have set the Source on Response, in the Text field, specify the text string that the Altio Presentation Server has to search to determine if the Service Function has been successfully executed. The Altio Presentation Server searches this text string in the document returned from the Application Server.
If you have set the Source to RESPONSE, choose one of the following options in the Type drop-down menu:
SUCCESS: the Service Function is considered to have succeeded if the response body matches part of the Text.
FAILURE: the Service Function is considered to have failed if the response body matches part of the Text.
Please note: In each case there must be a response text available.
If You have set the Source to RESPONSE or HEADER, from the On success Source drop-down menu, specify where to get the message to send to the AltioLive client when a service succeed. Choose one of the following:
NONE: no message will be sent to the client.
DEFINE: will return the value entered in the Text field.
HEADER: will return the Altio specific parameter (X-Altio-Message) in the HTTP response header.
If the On success Source parameter is set to DEFINE, enter the text to be sent to the client in the Text box . (If the Source is set to HEADER or NONE this setting is not available.)
From the On failure Source drop-down menu, specify where to get the message to send to the AltioLive client when a service failed. Choose one of the following:
NONE: no message will be sent to the client.
DEFINE: will return the value entered in the Text field.
HEADER: will return the Altio specific parameter (X-Altio-Message) in the HTTP response header.
If the On failure Source parameter is set to DEFINE, enter the text to be send to the client in the Text box . (If the Source is set to HEADER or NONE this setting is not available.)
Please note: This will not test any XSL transformation - the XML data returned will not be transformed.
The Test tab allows an HTTP Service to be tested.
Enter test values for any parameters. Any parameter in the request such as ${client.BID_ID} can have test values entered here. The test parameters list is automatically generated.
Click on the Test button. This displays the HTTP response's header and body. It also shows the URL and URL arguments used in the request and the size of the response.
A Test Results window is displayed with the requested data in whatever format the data is in, for example: XML or text. Images will be interpreted as text - in the same way as if, for example, they were opened in a text editor. If the Service Function fails, you will get an error message.
If it returns:
<DATA TIMESTAMP = 1>
or
<DATA WRAPPER='Y' TIMESTAMP='717'/>
then no data has been found, and you will have to change the XPath in your TARGET parameter.
For more information: see Xpath Syntax section.
If a WARNING message "No Datakey is defined for element NAME_ELEMENT" is displayed, you can click on the Extract Datakeys button in order to create a datakey for this element.
For more information: See the Setting up Datakeys section.
It is possible to open XML files directly from an HTTP Service Function, without needing to use a servlet such as AltioDB Manager.
In the Service Function, the URL should point directly to the file. No URL arguments are required.
|
Name |
Get XML data |
|
Document Type |
XML |
|
URL |
${db.server.protocol}://${db.server.name}:${db.server.port}/${aps.context}/myFile.xml |
|
Method |
Auto |
|
URL Argument |
|
|
Add Quotes |
(unchecked) |
This will return the contents of the file. The contents of the file are returned in the same manner as a GET action.
This method will get a file which can be reached by the Application Server. Alternatively, the URL can point directly to any file on the server. Use a URL like that below:
file:///C:/myotherfile.xml
Like any other Service Function, this can be executed as part of the initial data when the applet loads, or triggered by a Server request action on the client.
The HTTP service picks up the JVM proxy settings. To configure the http proxy settings, you need to set system properties. Please see http://java.sun.com/j2se/1.4/docs/guide/net/properties.html for more information about HTTP proxy settings.