com.worklight.wlclient.api

Class WLClient

  • java.lang.Object
    • com.worklight.wlclient.api.WLClient

  • public class WLClient
extends java.lang.Object
    This singleton class exposes methods that you use to communicate with the IBM MobileFirst Platform Server.

    • Method Detail

      • createInstance

        public static WLClient createInstance(javax.microedition.midlet.MIDlet midlet)
        This methods create the singleton instance of WLClient.

        Note:This method is the first WLClient method that you use.
        It must be called before subsequent calls to getInstance(). If the client device is BlackBerry, connection parameters such as deviceside=true,interface =wifi, or any name-value pairs that you can use to identify connection type can be passed as string arguments. For other devices, you can set the string argument to null.

        Parameters:
        midlet - This parameter is the MIDlet instance, for example the midlet that creates the WLClient.
        Returns:
        WLClient WLClient

      • createInstance

        public static WLClient createInstance(java.lang.String connectionString,
                      javax.microedition.midlet.MIDlet midlet)
        This methods create the singleton instance of WLClient.

        Note:This method is the first WLClient method that you use.
        It must be called before subsequent calls to WLClient.getInstance(). If the client device is BlackBerry, connection parameters such as deviceside=true,interface =wifi, or any name-value pairs that you can use to identify connection type can be passed as string arguments. For other devices, you can set the string argument to null.

        Parameters:
        connectionString - Specifies the connection string to be used to connect to the server from a BlackBerry device. For other devices, it can be set to null.
        midlet - This parameter is the MIDlet instance, for example the midlet that creates the WLClient.

      • getInstance

        public static WLClient getInstance()
        This method gets the singleton instance of WLClient.
        Returns:
        WLClient

      • connect

        public void connect(WLResponseListener responseListener)
        This method sends an initialization request to the IBM MobileFirst Platform Server, establishes a connection with the server, and validates the application version.

        Important:You must call this method before any other WLClient methods that communicate with the IBM MobileFirst Platform Server. If the IBM MobileFirst Platform server runs in secured mode (over https), then ensure that the security certificate that the server uses is imported to the device else the connection will fail.

        Parameters:
        responseListener - When a successful response is returned from the server, the WLResponseListener onSuccess method is called. If an error occurs, the onFailure method is called.

      • invokeProcedure

        public void invokeProcedure(WLProcedureInvocationData invocationData,
                   WLResponseListener responseListener,
                   WLRequestOptions requestOptions)
        This method sends an asynchronous call to an adapter procedure. The response is returned to the callback functions of the provided responseListener.
        If the invocation succeeds, onSuccess is called. If it fails, onFailure is called.
        Parameters:
        invocationData - The invocation data for the procedure call.
        responseListener - The listener object whose callback methods onSuccess and onFailure are called.
        requestOptions - Optional. Invocation WLRequestOptions.

      • invokeProcedure

        public void invokeProcedure(WLProcedureInvocationData invocationData,
                   WLResponseListener responseListener)
        Invokes an adapter procedure (Similar to the JavaScript WL.Client.invokeProcedure). the response is returned to the supplied listener callback functions.
        Upon a successful response from the server, the listener's onSuccess is called. onFailure is called in case of an error, including a login form response from the server, which is also considered an error. however, if the WLAuthListener is set, WLClient calls the WLAuthListener handleLoginResponse in case a login response is returned from the server.
        Parameters:
        invocationData - The invocation data parameters to send on the request.
        responseListener - The listener that will handle the response when return from the server (success or failure).

      • logActivity

        public void logActivity(java.lang.String activityType)
        This method reports a user activity for auditing or reporting purposes. The activity is stored in the raw table of the IBM MobileFirst Platform Server.

        Important:Ensure that reports.exportRawData is set to true in the worklight.properties file, else the activity is not stored in the database.

        Parameters:
        activityType - a String that identifies the activity.

      • setHeartBeatInterval

        public void setHeartBeatInterval(int newInterval)
        This method sets the interval, in seconds, at which the heartbeat signal is sent to the IBM MobileFirst Platform Server. Use the heartbeat signal to ensure that the session with the server is kept alive when the app does not issue any call to the server, such as invokeProcedure. By default, the interval is set to 7 minutes.
        Parameters:
        newInterval - An integer value that defines the interval in seconds between the heartbeat messages that WLClient automatically sends to the IBM MobileFirst Platform Server. To disable the heartbeat, set a value that is less than, or equal to zero.

      • registerChallengeHandler

        public void registerChallengeHandler(BaseChallengeHandler challengeHandler)
        You can use this method to register a Challenge Handler in the client. You must use this method when you implement custom challenge handlers, or when you customize the Remote Disable / Notify Challenge Handler.
        Important: you must call this method at the beginning of your application after you initialize WLClient.

        Example 1: registering a customized Remote Disable / Notify Challenge Handler

        To customize the Remote Disable / Notify ChallengeHandler, you must register an instance of type WLChallengeHandler in the client. When you create the Challenge Handler, you must name it with the specific realm name wl_remoteDisableRealm. 

                
          // define class
                                public class MyRemoteDisableCH extends WLChallengeHandler {
                                .
                                .
                                .
                                }
                                // create new CH with appropriate realm
                                MyRemoteDisableCH ch = new
                                MyRemoteDisableCH("wl_remoteDisableRealm");
                                // register CH
                                WLClient.getInstance().registerChallengeHandler(ch);

        Example 2: customizing the Remote Disable / Notify Challenge Handler

        To customize the Remote Disable / Notify Challenge Handler, you must extend WLChallengeHandler and implement the following methods:

        • public void handleSuccess(JSONObject success)
        • public void handleFailure(JSONObject error)
        • public void handleChallenge(JSONObject challenge)

                
                public MyRemoteDisableCH(String realm) {
                                super(realm);
                                }

                                // this method is called after the challenge is answered successfully

                                public void handleSuccess(JSONObject success) {
                                }
                                //this method is used to disable the application

                                public void handleFailure(JSONObject error) {
                                try {
                                // get error message
                                String message = error.getString("message");
                                // get download link
                                String downloadLink = error.getString("downloadLink");
                                // create and show the disable dialog
                                } catch (JSONException e) {
                                // handle exception
                                }
                                }
                                //this method is used to notify the application

                                public void handleChallenge(JSONObject challenge) {
                                try {
                                // get message data from challenge
                                String message = challenge.getString("message");
                                String messageId = challenge.getString("messageId");
                                // do something with the message
                                // answer the challenge
                                submitChallengeAnswer(messageId);
                                } catch (JSONException e) {
                         // handle exception
                    }
               }
          }

        Note: When the application is disabled, the behavior by default is to open a dialog that displays the appropriate message. You must implement this behavior by default in the method handleFailure of RemoteDisableChallengeHandler. The dialog can also display a link to download the new version of the application. After the user closes the dialog, the application closes. You must implement a similar behavior in the handleFailure code of the custom Remote Disable Challenge Handler.

        Parameters:
        challengeHandler - BaseChallengeHandler

      • addGlobalHeader

        public void addGlobalHeader(java.lang.String headerName,
                   java.lang.String value)
        You use this method to add a global header, which is sent on each request.
        Parameters:
        headerName - The name of the header
        value - The value of the header

      • removeGlobalHeader

        public void removeGlobalHeader(java.lang.String headerName)
        You use this method to remove a global header. Then, the header is no longer sent on each request.
        Parameters:
        headerName - Than name of the header
  • Summary: 
  • Nested | 
  • Field | 
  • Constr | 
  • Method
  • Detail: 
  • Field | 
  • Constr | 
  • Method


© Copyright IBM Corp. 2006, 2015. All Rights Reserved.