First steps

Once you have at least the beginning of a service (see About the components), you are all set to start using the PureWeb APIs.

The first few lines of code must be to initialize the State Manager classes, which do the heavy lifting under the hood.

The next steps should be to make a simple API call from the service and the client to establish the connections between the components.

Finally, you will need to configure a plug-in file for the PureWeb server, so that it knows where to find your application.

If you are new to PureWeb, we strongly recommend that you build a sample application first before performing the steps on this page; This will give you a feel for the connection workflow on the PureWeb server, provide a working example of an application plug-in file, as well as sample connection code to which you can refer..

Steps

Initialize the State Manager

APIs:

StateManager | C++ | .Net | Java

StateManagerServer | C++ | .Net | Java

To set the PureWeb wheels in motion, you must first initialize the State Manager classes in your service application. These classes are responsible for managing PureWeb under the hood:

  • StateManager is responsible for creating and updating application state, responding to input events and commands sent from the client, and generating responses such as updated images in views to send back to the client application.
  • StateManagerServer implements an input/output thread to receive input and commands from the client, as well as to send responses back. This thread is primarily intended for internal use by the APIs, but you can use it if it suits your need.

You must provide a name for your service application in the constructor for the StateManager class. This name is for information purposes only.

The initialization code is usually called from the application's main function. As you can see below, PureWeb API calls use the syntax of your chosen programming language.

C++

server = new CSI::PureWeb::Server::StateManagerServer();
StateManager = new CSI::PureWeb::Server::StateManager("MyServiceApp");

The CSI namespace is the root for all other namespaces in the C++ API, The acronym stands for "Calgary Scientific Inc.", the company that makes PureWeb.

.Net

StateManager = new PureWeb.Server.StateManager("MyServiceApp", Dispatcher.CurrentDispatcher);
StateManagerServer server = new StateManagerServer();			

In .Net, one of the arguments for the StateManager constructor is the dispatcher associated with the UI thread. Typically you will pass the dispatcher for the thread on which your application is currently running. Alternatively, you could create a new thread, and pass the dispatcher for that thread.

Java

stateManager = new StateManager("MyServiceApp");
stateManagerServer = new StateManagerServer();

Initialization events

The StateManager object fires an event when it has been successfully initialized or uninitialized. A handler can be chained to the event.

For example, you can attach a handler to an initialization event that will load initial values for some properties, or attach a handler to an uninitialization event to gracefully disconnect the application.

C++

StateManager->Initialized() += Bind(this, &MyApp::OnStateInitialized);
void MyApp::OnStateInitialized(StateManager& stateManager, EmptyEventArgs&)
{
    // Do something useful 
}				
StateManager->Uninitialized() += OnPureWebShutdown;
static void OnPureWebShutdown(CSI::PureWeb::Server::StateManager&, CSI::EmptyEventArgs&)
{
    // Do something useful 
}				

.Net

StateManager.Initialized += new EventHandler(OnStateInitialized);
private void OnStateInitialized(object sender, EventArgs args)
{
    // Do something useful
}
StateManager.Uninitialized += new EventHandler(OnPureWebShutdown);
static void OnPureWebShutdown(object sender, EventArgs e)
{
    // Do something useful
}

Java

stateManager.addInitializedHandler(new OnStateInitialized());
private class OnStateInitialized implements EventHandler<EmptyArgs>
{
    public void invoke(Object sender, EmptyArgs args)
    {
        // Do something useful
    }
}

stateManager.addUninitializedHandler(new OnPureWebShutdown());
private class OnPureWebShutdown implements EventHandler<EmptyArgs>
{
    public void invoke(Object sender, EmptyArgs args)
    {
        // Do something useful
    }
}

Once the State Manager classes are initialized, you are ready to start using the full spectrum of PureWeb APIs. Your next step should be to set up the connection between the service and the PureWeb server.


Connect the service

APIs:

StateManagerServer.start() | C++ | .Net | Java

To connect a service to the PureWeb server and establish a session, you simply call the start method.

This section assumes that you are connecting a managed service, where the PureWeb server manages the entire application life cycle under the hood, which is by far the most common scenario (see Connection workflow). However, you can also connect a service as unmanaged; the instructions are provided here.

In a managed service, the PureWeb server and the service application are deployed on the same node, and there is no need to explicitly provide the start method with any optional parameter. The code is very simple:

C++

server->Start(stateManager.get());

.Net

server.Start(StateManager);			

Java

server.start(stateManager);			

You can configure rules for service-server interactions (such as timeout values) in the PureWeb server configuration files. For more information, see Service-server interaction properties.


Connect the client

To connect a client, you must first set up files for this client, and then add a simple API call for the connection itself.

Set up the client files

The bare minimum before you can connect a client and configure it on the PureWeb server is to have a stub of a basic application, just enough to get you to the point where you can add your first method call. How you go about this varies depending on the platform you chose for your client. For example, if creating an HTML5 client, this would be an .html file and a single js file where you will add the connection code. If creating an iOS or Android mobile app, this means creating a single view application, with a main function where you can add the connection code.

The connection code itself requires just a single line, as described below. This will be sufficient for you to configure your application on the PureWeb server and confirm that everything was set up properly.

Add the connection code

APIs:

WebClient.connect() | HTML5 | Android
PWWebClient.connect() | iOS

To connect a client, you simply call the connect method. This method expects the application URL in its arguments. This call is usually added to the client's initialization code.

HTML5

pureweb.connect(location.href);					

iOS (Obj-C)

[framework.client connect:@"http://myhostname:8080/pureweb/app?name=MyServiceApp"];				

Although in this example the launch URL is hard-coded in the method call, typically it would be stored in a variable. For instance, in the Scribble and Asteroid sample clients, the end user must provide this URL in the app's settings.

Android

framework.getWebClient().connect("http://myhostname:8080/pureweb/app?name=MyServiceApp");

Although in this example the launch URL is hard-coded in the method call, typically it would be stored in a variable. For instance, in the Scribble and Asteroid sample clients, the end user must provide this URL in the app's settings.

The connect method also has a few optional parameters, allowing you to pass additional information, such as:

  • authentication credentials

    These credentials are created differently depending on the client platform. They are expressed as a key-value pair in HTML5, a PWBasicAuthorizationInfo object in iOS, or a BasicAuthorizationHeader in Android.

  • any other custom connection parameter that you wish to include

    Passing custom connection parameters is rare. If you need to do this, first create an array of key-value strings and pass this array as an argument of the connect call. You can convert the parameters to different data types when you retrieve them from the service, where they will be available in the SessionConnected event (emitted by the StateManager class).

You can configure rules for client-server interactions in the PureWeb server configuration files, such as client activity timeout and user process limit. For more information, see Client-server interaction properties.

Monitor changes to the connection status

While setting up the client connection, it is common to also add handlers for connection events, so that you can gracefully disconnect your client, or respond appropriately if the connection to the service is unexpectedly lost.

To set this up, you must register for the event in your client application. The snippet below illustrates how to listen for the client-side "connected changed" event. See Useful PureWeb events for a list of other common events for which you can register.

HTML5

pureweb.listen(client, pureweb.client.WebClient.EventType.CONNECTED_CHANGED, onConnectedChanged);					

iOS (Obj-C)

[_framework.client.isConnectedChanged addSubscriber:self action:@selector(onConnectedChanged)];				

Android

webclient.addConnectedChangedHandler(new onConnectedChanged());	


Configure the application as a plug-in on the PureWeb server

Configuring your application on the PureWeb server will enable you to confirm that you have set up the connections correctly.

This configuration is a system administration task which does not involve the APIs.

The initial step may be more time-consuming as it requires to create an application plug-in file, but once this is done, you will be able to refresh the server anytime with your latest development changes by simply reloading the plug-ins at the touch of a button.

The quickest way to create a plug-in file for your application is to edit an existing one. See Add application plug-ins to the PureWeb server.

Verify the connections

Once you have added the application plug-in to the PureWeb server, here's how you can verify that the connections are set up correctly:

  1. Go to the server's Apps page. It should list your application, and provide a launch button for the client.
  2. Click the launch button. If successful, this should launch the service, connect to the PureWeb server, then launch the client and connect it to the running service session.
     

    Since your client doesn't actually have a UI yet, the best way to confirm that its connection is working is through the PureWeb log in the server's console. Look for a message like this:

    SessionSocketConnection Starting web socket response loop (for HTML5 clients)

    Creating new queue for responses for connectionId: X (for mobile apps)


After the one-time steps on this page are completed, you are ready to jump right in and start creating your solution. Don't forget to check the sample applications as they provide working examples.

We recommend that you begin by adding a view.