a
Setting the JAVA Service Functions
A JAVA service function provides easier and efficient way to interface backend services. It allows calling a method of a JAVA class on a local machine (JVM) or a remote machine. The class can be an arbitrary JAVA class or an Altio service adapter. Invoking a method from Altio service adapter is more efficient than a method from an arbitrary class, because it calls expected method directly, rather than using JAVA reflection. Calling an Altio service adapter service is also more efficient than calling a HTTP service.
From the Application Manager do one of the following:
Click
on the New JAVA service button 
in the toolbar.
Click on the Edit|New JAVA service menu item.
Right-click on the Services node in the Application Explorer window and select New JAVA service in the context menu.
A Service Function is added to the Services node with the default name of JAVA SERVICEn. The following Java Service details window will be opened:
The Request tab specifies how the JAVA Service function is executed.
In the Service name field enter the name by which the Service Function is referenced.
From the Java Class drop-down menu choose one of the following:
LOCAL: If the Java class exists in the same JVM with the Presentation Server.
REMOTE: Choose this option otherwise.
Service Class Scope: When invoking a Java method, Presentation Server needs to create an instance of the specified Java class. This field let you configure the service where to get an instance of this Java class. If the service is invoked the first time, Presentation Server will instantiate this Java class and cache the instance depending on the setting of this field. This field does not apply if the Java method is a static method. Choose one of the following class:
NONE: Select this value if you want the service always creates an instance of the specified Java class.
SERVICE: Select this value to cache the Java class instance in the service. When same service is invoked again, same Java class instance is reused. This Java class instance is deleted when the Java service is destroyed.
APP: Select this value to cache the Java class instance in the application. Within the same application when any Java services using same Java class are invoked, they all use the same Java class instance. This Java class instance is deleted when the application is stopped.
PS: Select this value to cache the Java class instance in the Presentation Server. Within Presentation Server when any Java services using the same Java class are invoked, they all use the same Java class instance. This Java class instance is deleted when the Presentation Server is stopped.
If the Java class is a local class, enter in the Class name field a fully qualified class name (for example: com.altio.demo.services.DateService). Or if the Java class is a remote class, enter the RMI reference of the remote class (for example: rmi://localhost:8099/RmiDateServer). If you specify the Java class is a remote class, a "Browse" button will be available to list what are registered at specified host and port.
Tick the This is a service adapter option if your Java class is an Altio Service Adapter. If you tick this option the Java method name field is automatically set to processRequest. Making your Java class an Altio Service Adapter allows Presentation Server to call a Java method directly rather than using reflection. If your application needs to execute a Java service frequently (for example: datapool), this can improve the system performance.
In the Java Method Name field enter the name of the Java method defined in the Java class.
The Return Data Type is a non-editable field. This value is set when you click Browse button and select a method. It is for information only and you cannot set the value manually .
After specifying the Java class/RMI Reference, click on the Browse button to get a list of methods. You can then select one and all required arguments are automatically populated in the Argument mapping list.
Set the Argument box:
From the Java method takes drop-down menu, choose one of the following argument type:
NO: Java method takes no argument.
OBJECT: Java method takes argument(s) of specified type(s).
HASHTABLE: Java method takes single argument of Hashtable which contains object(s) of specified type(s).
If OBJECT or HASHTABLE type of argument is selected, this list is activated. You can define all argument(s) that Java method expects.
To add an argument, click on the Add button.
In the Name cell enter the name of the argument.
From the
Type drop-down menu select one predefined types from the
following list :
boolean or Java.lang.Boolean
byte or java.lang.Byte
double or java.lang.Double
float or java.lang.Float
int or java.lang.Integer
long or java.lang.Long
short or java.lang.Short
java.lang.String
java.math.BigInteger
java.math.BigDecimal
Javax.servlet.http.HttpServletRequest
Javax.servlet.http.HttpSession
java.util.Date
xml-string – Presentation Server will ensures the argument
is a well formed XML string
XmlElement – Altio's implementation of XML data structure
or specify your own type by specifying a fully qualified Java
class name. If you specify your own type, make sure it exists in local
JVM and it has a constructor that takes a String (java.lang.String).
In the Value cell, enter a value. It can be a static string or an Altio property.
In the Default cell enter a value which will be used when the service is invoked and the value is not provided or when there is an unresolved property reference (for example: ${client.xxx} in datapool service).
To delete an argument from the Parameter mapping, select it and click on the Delete button.
To move selected argument up or down one position click on the Move Up or Move Down Buttons.
The Response tab configures how returned values from a Java method are processed. It is intended to be very flexible, with full control over the data that is returned to the client. In particular, if XML data is to be returned, then this can be formed from a combination of literal XML with reference to elements from the Java method response. For example:
Check this box if a Java method returns XML data. You will be able to define aliases with XPath reference to element of the return XML data.
If you specify that a Java method returns XML data, you can also specify if the returned data is Formatted in XML.
Normally when Use Default is selected, Presentation Server uses toString() to convert return data object to String, but there are some Objects of which toString() does not return good representation of the data. For example Array of String, Hashtable, Map, or Properties. For these objects, the Presentation Server will try to convert returned data to XML. You can also specify a different method (even explicitly specifying toString) to convert the return data. Specifying your own method to convert data to String is useful when the return object is defined only in the remote JVM, because toString() only returns the id of the remote object.
For more information about return data is converted to String, see the JAVA Service Response Processing section.
Please note: Alias is useful when you want to build your own XML return data from Java method's XML return data. In this case, you can define aliases and reference to them in "Literal XML string".
Name: The name of this alias.
XPath statement to run against response envelope: XPath to obtain the data represented by this alias.
Encode: Indicate when resolving the XPath of this alias, the result should be XML-encoded or not. This is useful when you want to make a XML block the value of an attribute or text() of an element.
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 also 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.
You can choose either XML or EMPTY. If this is set to XML, then 'Literal XML String' is evaluated to construct the XML to return.
When the Java method return data is not what you want to return to AltioLive client, you can define the return data represents the returned results. It can contain a generic string with property references. See JAVA Service Response Processing for more detail.
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.
You can find out more about how Presentation Server processes Java method return data from JAVA Service Response Processing.
The Acknowledgment tab is used to define how the success or failure of a Java 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:
NONE: it assumes the Java method executed successfully unless a Throwable is thrown from the Java method.
RESPONSE: you can check the response data (converted to String) to determine the execution status.
FORMATTED: execution status is determined from the <STATUS> element of the return data. Please refer to Formatted XML for information about Java method return status.
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. This field is available only if the Source parameter is set to RESPONSE.
If you have set 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
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.
FORMATTED: will return the message from the <STATUS> element of the Java method returned XML data.
If the On success 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.
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.
FORMATTED: will return the message from the <STATUS> element of the Java method returned XML data.
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: that this is not a simulated test. Whatever operation you test will be executed on your Java method, which may change the state of your Java class instance.
The Test tab allows a JAVA Service to be tested. When you click this tab, the Application Manager will verify if the service is defined correctly. If the service is not valid, a message will be shown.
In the Test value cell, enter a value to test the Service.
Click the Test Service button. A Test Results window is displayed with the execution messages and return data. See picture below:
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.
The Output Data tab shows the XML data that will be sent back to AltioLive client. You can also click Original Data tab to see the original data returned from the Java method. For example:
If the function fails, you will get an ERROR entry in the execution message list.
If the XML shown from the Output Data tab is not what you expect, you can go back to Response tab and modify the XML template of the Literal XML string and test the service again.
Formatting JAVA Return Data, Setting the JAVA Service Response Processing