XIMSS Client Library API

The Java XIMSS Client Library accepts "callback methods" specified as an Object reference and a String specifying the object method name to invoke.
For example, if there is an object X, and there is a method X.method1(paramA,paramB) that the XIMSS Client Library needs to call on a certain event, you should specify this "callback" as two parameters -
LibraryFunction(....,X,"method1",...)
The library checks if the class the object X belongs to does implement the specified method method1, and if this method accepts the proper number of parameters of the proper type. If this check fails, the XIMSS Client Library throws an exception.

To use a static method as a callback method, specify the method Class reference as the Object reference.
For example, if there is a class C, and there is a static method C.method2(paramA,paramB) that the XIMSS Client Library needs to call on a certain event, you should specify this "callback" as two parameters -
LibraryFunction(....,C.getClass(),"method2",...)

If the client application does not need to be notified when a certain event takes place, it should specify null as a method name.

package com.communigate.ximss;

//
// XIMSS Session object class
//
public class Session extends Object {
  public static String       getVersion();

  public static void         create(HashMap<String,String> params, Object theRef, String createCallbackName) 
                               throws Exception;
  public void                start();

  public void                sendRequest(org.w3c.dom.Element xmlRequest,
                                  Object theRef, String dataCallbackName, String finalCallbackName,
                                  boolean sendImmediately) throws Exception;
  public void                close(Object theRef, String finalCallbackName) throws Exception;
 
  public boolean             setAsyncProcessor(Object theRef, String asyncDataCallbackName,
                                  String tagName, String attrName, String attrValue)
                               throws Exception;
 
  public boolean             setNetworkErrorProcessor(Object theRef,String networkErrorCallbackName,
                                  int timeLimit)
                               throws Exception; 

  public boolean             setNetworkOKProcessor(Object theRef,String networkOKCallbackName)
                               throws Exception; 

  public org.w3c.dom.Element createXMLNode(String tagName);
  public org.w3c.dom.Node    createTextNode(String text);
  public static void         setCallbackFactory(CallbackFactory newFactory);
}

//
// Callback methods
//
  void    createCallback(Session newSession,String errorCode);
  void    dataCallback(org.w3c.dom.Element xmlData,org.w3c.dom.Element xmlRequest);
  void    finalCallback(String errorCode,org.w3c.dom.Element xmlRequest);
  Object  asyncDataCallback(org.w3c.dom.Element xmlData);
  Boolean networkErrorCallback(Boolean isFatal,Integer tryingTimeInSeconds);
  void    networkOKCallback();

By default, the Java XIMSS Client Library invokes a "callback" method from its own processing thread, which can be a different one from the thread used to specify that method.
In some GUI environments, such as Swing this is not acceptable, as the "callback" methods should be invoked from the "GUI threads" only - to allow the code of these methods to use the GUI functions.
To accomodate for these restrictions use the setCallbackFactory static method with a "callback factory" implementing a platform-specific callback mechanism.
The XIMSSLibSwing.jar package implements the swingCallbackFactory "factory" class for the Swing platform, and the XIMSSLibAndroid.jar package implements the androidCallbackFactory "factory" class for the Android platform.

#import com.communigate.ximss.*;
#import com.communigate.ximss.swingCallbackFactory.*;

...
   XIMSS.Session.setCallbackFactory(new swingCallbackFactory());
...

The networkErrorCallback and networkOKCallback callback methods are always called directly, using the Java XIMSS Client Library own processing thread.

The JavaScript version of the XIMSS Client Library accepts "callback methods" specified as an object reference and a function method reference. The specified method is invoked for the specified object.

This JavaScript file defines a XIMSSSession "constructor" function:

//
// XIMSSSession object constructor
//
function XIMSSSession(params,theRef,createCallback) {
  this.start                    = function() {...}
  this.sendRequest              = function(xmlRequest,theRef,dataCallback,finalCallback,sendImmediately) {...}
  this.close                    = function(theRef,finalCallback) {...}

  this.setAsyncProcessor        = function(theRef,asyncDataCallback,tagName,attrName,attrValue) {...}
  this.setNetworkErrorProcessor = function(theRef,networkErrorCallback,timeLimit) {...}

  this.createXMLNode            = function(tagName) {...}
  this.createTextNode           = function(text) {...}

  this.setDebugFunction         = function(theRef,debugCallback) {...}
}

// "static" methods
XIMSSSession.prototype.getVersion = function() {...}

//
// Callback methods
//
  function createCallback(newSession,errorCode);
  function dataCallback(xmlData,xmlRequest);
  function finalCallback(errorCode,xmlRequest);
  function asyncDataCallback(xmlData);
  function networkErrorCallback(isFatal,tryingTimeInSeconds);
  function debugCallback(tag,debugString);

Use the setDebugFunction method to set an object and its method to be used as an internal debugging facility. This method is called with 2 string parameters - the name of the internal library component and the log record text.

The Objective C version of the XIMSS Client Library accepts "callback methods" specified as an object reference and a method selector. You can use the @selector(methodName) syntax construct to specify the method selector. The specified method is invoked for the specified object.

To use a class method as a callback method, specify the method class as the "object reference".

If the client application does not need to be notified when a certain event takes place, it should specify nil as a method selector.

Since the iOS platforms do not include solid XML support, the XIMSS Client libraries for these platforms include a basic XML object implementation.
On the MacOSX platform, the XIMSS Client library provides the same methods for the Apple's NSXMLElement object.
To simplify application porting, the XIMSS Library defines the XIMSSXML class as either the Apple NSXMLElement object (MacOS X) or the Library-provided STXML object (iOS).

//
// XIMSSSession object Class
//
@interface XIMSSSession : NSObject {
 
}
+(NSString*)getVersion;
+(void)create:(NSDictionary*)params delegate:(NSObject*)delegate onCompletion:(SEL)createCallbackSelector;
-(void)start;
-(void)sendRequest:(XIMSSXML*)xmlRequest delegate:(NSObject*)delegate onData:(SEL)dataCallbackSelector
      onCompletion:(SEL)finalCallbackSelector  sendImmediately:(bool)doImmediately;
-(void)close:(NSObject*)theRef onCompletion:(SEL)finalCallbackSelector;
-(bool)setAsyncProcessor:(NSObject*)delegate selector:(SEL)asyncDataCallbackSelector
                 tagName:(NSString*)tagName attrName:(NSString*)attrName attrValue:(NSString*)attrValue;
-(bool)setNetworkErrorProcessor:(NSObject*)delegate selector:(SEL)networkErrorCallbackSelector
                      timeLimit:(unsigned)timeLimit;
-(bool)setNetworkOKProcessor:(NSObject*)delegate selector:(SEL)networkOKCallbackSelector;
@end

//
// Callback methods
//
-(void)createCallback:(XIMSSSession*)newSession errorCode:(NSString*)errorCode;
-(void)dataCallback:(XIMSSXML*)xmlData xmlRequest:(XIMSSXML*)xmlRequest);
-(void)finalCallback:(NSString*)errorCode xmlRequest:(XIMSSXML*)xmlRequest;
-(id)asyncDataCallback:(XIMSSXML*)xmlData;
-(id)networkErrorCallback:(bool*)pIsFatal elapsedTime:(int*)pTryingTimeInSeconds;
-(void)networkOKCallback;

Note: networkErrorCallback should return a non-null value to .

Note: when linking your application against the XIMSS Library, add the -ObjC flag to the application Other Linker Flags.

A client can perform certain operations without creating a XIMSS Session.

To check the XIMSS Client Library version, the client application should use the getVersion static method. It returns a string with the Library version.

A client starts communicating with a XIMSS Server by creating a XIMSS Session. Requests and response messages are sent within a context of that Session.

The XIMSS Client SDK can support several independent XIMSS sessions - to the same Account or to different Accounts, on the same Server or on different Servers.

To open a new XIMSS Session, the client application needs to use the create static method or the XIMSS Session constructor method. This method accepts the following parameters:

params

A "dictionary" with session creation parameters (with JavaScript, an Object is used as a dictionary).
The dictionary keys and values should be strings. The following keys-value pairs are supported:

serverName

the IP address or a fully qualified domain name of the XIMSS server to connect to. The value can contain the :number suffix, where the number explicitly specifies the port to connect to.

binding

supported values: HTTP, TCP. This parameter specifies the XIMSS protocol binding to use. The JavaScript Library supports the HTTP binding only.

secureMode

optional. If this key exists and its value is YES, the session should be established using a secure (encrypted) mechanism - TLS for the TCP binding, https for the HTTP binding.

acceptAllCerts

optional. If this key exists and its value is YES, and the secureMode value is also YES, then the server SSL/TLS certificate is not checked for validity and expiration.

loginMethod

supported values:

plain

The Library will use the "plain" or "clear text" login method - the params dictionary should contain the userName and password pairs with the user credentials.

cram-md5

The Library will use the "CRAM-MD5" login method - the params dictionary should contain the userName and password pairs with the user credentials.
Note: this method is not currently supported in JavaScript.

auto

If the Server supports it the "CRAM-MD5" login method, the Library will use it. Otherwise if the Server supports it the "plain" login method, the Library will use it. the userName and password pairs with the user credentials.

sessionid

The Library will use the "sessionid" login method, - the params dictionary should contain the userName pair the and sessionid pair containing the "session id" of a currently existing session created for the same user.

auth

The Library will use the HTTP Authentication login method - the params dictionary should contain the userName and password pairs with the user credentials. This method may not be supported on some platforms.

asyncMode

This parameter is used for the HTTP binding only; supported values:

syncPOST

the Library will use HTTP POST requests to send XIMSS requests to the server and receive the XIMSS responses and synchronous data messages in HTTP POST responses.
The Library will maintain a pending HTTP GET request to receive asynchronous data messages.

asyncPOST

the Library will use HTTP POST requests to send XIMSS requests to the server, and the server will send empty responses to these HTTP POST requests.
The Library will maintain a pending HTTP GET request to receive the XIMSS responses, synchronous data messages, and asynchronous data messages.

noAsync

the Library will use HTTP POST requests to send XIMSS requests to the server, and receive the XIMSS responses, synchronous, and asynchronous data messages data messages in HTTP POST responses.
The Library will not maintain a pending HTTP GET request; asynchronous data messages are not seen by the client application till the next HTTP POST request is sent to the server.

fixedIP

This optional parameter is used for the HTTP binding only; if it is specified and its value is NO, then the XIMSS session client IP control is explicitly switched off, so the client can proceed to use the XIMSS session if its IP Address has changed.

useCookie

This optional parameter is used for the HTTP binding only; if it is specified and its value is NO, then the XIMSS session Cookie set/check mechanism is explicitly switched off.

pollPeriod

supported value: a numeric string. It specifies the time period (in seconds) that the Library waits after sending a XIMSS request to the server. If no new request is submitted by the client application over this period of time, the Library sends a noop request to the server to maintain a connection and to avoid session termination due to inactivity timeouts.

theRef, createCallback

the object and its method to invoke when the session creation process completes.
The createCallback method should have 2 parameters: if the session is successfully created, the first parameter contains the newly created XIMSS Session object, and the second parameter is null.
If the session could not be created, the first parameters is null, and the second parameter contains the error code text.
Note: if this method is implemented as a constructor (as in the JavaScript Library), its result should be discarded. When the XIMSS Session object is fully created, it is passed as a parameter to the createCallback method which should store it.

Before this method is invoked, the client application should set all required processors (for asynchronous data messages, for network failures, etc.)

When this method is invoked all asynchronous data messages received during the session creation operation are processed.

The client application should not specify the id attribute of the request - it will be set within the Library.

If the Library provides the createXMLNode and createTextNode methods, these methods MUST be used to compose XIMSS requests.

A composed XIMSS request should be submitted to the XIMSS Session object using the sendRequest method, with the following parameters:

xmlRequest

an XML Element with the composed XIMSS request.

theRef, dataCallback, finalCallback

an object and its methods to be called when the Library receives XIMSS synchronous data messages for this request and when the Library receives the response message for this request.
The dataCallback method parameters are the XML element with the synchronous data messages, and the XML element with the XIMSS request sent to the server. This method is called once for each synchronous data message received in response to the XIMSS request sent.
The finalCallback method is called when the server sends a response XML element with the request completion code. The method parameters are a string with the request completion error code (null/nil if the request completed successfully), and the XML element with the XIMSS request sent to the server.

sendImmediately

this boolean parameter can be sent to false if the client application knows that it will immediately issue more requests, telling the Library to buffer this request and send it together with the next XIMSS requests the client application plans to submit.

A client application does not need to wait for a XIMSS request to complete (and for the finalCallback method to be called) before sending a new XIMSS request to the server.

A client application should use the setAsyncProcessor method with the following parameters:

theRef, asyncDataCallback

the object and its method to invoke when the specified asynchronous data message is received from the server.

tagName, attrName, attrValue

If all these parameters are strings, the specified method is invoked for all asynchronous data messages that have the specified tag and the specified attribute with the specified attribute value.
For example, if the tagName parameter is readIM, the attrName parameter is peer, and the attrValue parameter is user@domain, the specified method will be invoked for the following asynchronous data messages: <readIM peer="user@domain" ...>...</readIM>, i.e. for all incoming instant messages from the user@domain address.
If the attrValue parameter is null/nil, then the method is invoked for all asynchronous data messages that have the specified tag and the specified attribute is present (with any attribute value).
If the attrName parameter is null/nil, the attrValue parameter must be null/nil, too. The method is invoked for all asynchronous data messages that have the specified tag (and any attributes).
If the tagName parameter is null/nil, the attrName and attrValue parameters must be null/nil, too. The method is invoked for all asynchronous data messages (with any tag).

When an asynchronous data message is received, the Library builds a sequence of methods to invoke:

The Library invokes the methods in the sequence one by one, passing the received data message as the parameter.

The Library checks the value each invoked method returns. If this value is the data message passed to the method, the Library does not invoke other methods remaining in the sequence built.

If there is already a processor registered for the same set of parameters (tag name, attribute name, attribute value), then the setAsyncProcessor method returns false. Otherwise, it returns true.

To unregister a processor, the client application should use the same XIMSS Session setAsyncProcessor method and specify null/nil as the object to register. If there was a processor registered for this set of parameters (tag name, attribute name, attribute value), then the registered object and its method are removed, and the setAsyncProcessor method returns true. Otherwise, it returns false.

The Library invokes the specified method when it encounters a "fatal" error (such as a TCP connection reset) and when it encounters a transient error (such as an HTTP transaction timeout).

A client application should use the setNetworkErrorProcessor method with the following parameters:

theRef, networkErrorCallback

the object and its method to invoke when the Library encounters a communication problem.

timeLimit

when the Library encounters transient errors, it invokes the specified method not more that once during the time period specified with this parameter (the parameter value is the number of seconds).

The specified method should have two parameters: a boolean parameter (or a pointer to one) set to true if the encountered error is a "fatal" one, and the time (in seconds) the Library is trying to recover from a transient error condition.

The specified method should return a boolean value. If it returns true (for example, if the transient error condition is longer than the application-specific limit, then the encountered error is treated as a fatal one.
On some platforms, the function should return a pointer instead of a boolean value. In this case, any non-null pointer is interpreted as the true value.

When the Library encounters a fatal error, or if the Library encounters a transient error, but the registered networkErrorCallback method returned a true-value, the Library completes all pending XIMSS requests with the communication error completion code. The Library then closes the XIMSS Session.

When the server terminates a XIMSS session, the situation is processed as a fatal communication problem.

A client application can register an object and its method with a XIMSS session object using the setNetworkOKProcessor method, and the Library invokes this method when communication with the server is restored after the library has invoked the networkErrorCallback method.

theRef, finalCallback

the object and its method to invoke when the Library completes Session closing.