Clients

This page discusses the clients that have been developed as part of the core M3 subsystem. The code is located in m3/clients.

In the future, we may move the client code to another location, and they may support communicating with more than just the M3 API.

PHP Client

ringside/m3/client/AbstractRestClient.php is the base abstract class for any REST client. It has no notion of any "social" information, such as user IDs, app IDs, or network IDs. But it has infrastructure in place that can properly prepare and encode parameters, sign the requests by generating proper D5 signatures and perform the low level comm. If curl is available, HTTP proxying is supported.

This abstract class was designed to be extensible. The messaging lifecycle is written in such a way that the methods can be overridden by any subclasses to allow for the protocol to be specialized and extended for things like requiring sessions and attaching user IDs to the request parameters.

There are plans to introduce Facebook and Ringside extensions to this class to allow you to call Facebook API and Ringside API. There is already a concrete extension to this class that allows you to call M3 API. The class is called M3_Client_RestClient and is located at ringside/m3/client/RestClient.php. This class provides methods to directly communicate with the M3 subsystem via explicit methods that correspond to the M3 REST API methods.

Java Client

The Ringside Java Client currently supports the M3 API and is extensible to support any REST API running in a Ringside Server. There are plans to extend the Java client to support the Facebook API and the Ringside API.

The Java client code is javadoc'ed - please refer to that documentation if you need more information on the Java client that is not covered here.

How to build the client

The Ringside Java client is available as a Maven module. To build it, ensure your Java environment is setup and execute "mvn install" from the top level directory of the Java client source (currently at m3/clients/java/ringside-java-client). This will run the system tests by default - if you do not have a Ringside Server currently running, you can disable the system tests by providing the "-Dtest.excludedGroups=system" property: mvn -Dtest.excludedGroups=system install.

Client

The class org.ringside.client.Client is an abstract class that the concrete Client classes can extend. It is a very small class that simply provides infrastructure to manage a Context object. Context objects are described below.

Concrete subclasses to this Client will provide access to M3, Facebook and Ringside and custom extension APIs hosted in a Ringside Server. There is an M3 client provided via the class org.ringside.client.api.m3.M3Client.

Clients create their own context and share their context with their internal components. This allows the client to create multiple senders but have each sender share data amongst themselves (such as session information, the last request ID, last request time, or custom data that handlers might want to share with each other).

Clients can create one or more RestSender objects that is will use to actually send requests to the Ringside server. Clients can (and in the M3 client case, actually does) have more than one internal RestSender. You would want to do this if you want to provide your client users with the ability to get responses in different formats (e.g. as XML DOM documents and JAXB POJO objects). See the org.ringside.client.api.m3.M3Client public methods for what this would look like and why it is helpful.

Context

Most of the components of the Java client have access to a "context" (org.ringside.client.Context). This context object contains some data about the client such as the server's URL endpoint, the secret key used to authenticate with the server, configuration properties and an area to house custom data that client components can use to store their own data.

The idea of the context is to have one object that can be shared across all handlers and senders within a client. It can be used, for example, by handlers to store session information.

RestSender

The class org.ringside.client.RestSender is the class that is used to actually build and send the REST request. It is designed to be extensible to allow for more specialized processing should it be needed (most methods are protected or public allowing for subclasses to override them as needed). The RestSender is configurable via the context configuration (this is how you can enable the HTTP proxy settings). The RestSender is associated with a request handler and a response handler. Creators of the RestSender must provide it with these handlers. These handlers perform the necessary actions to prepare the request and process the response. See below for more information on the handlers.

Request Handlers

Request handlers are implemented to perform certain tasks in order to build proper requests to the Ringside Server. Request handlers will be asked to:

1. prepare parameters so they can be sent over the wire to the Ringside Server
2. sign the request by generating the proper signature
3. connect to the server

There is one base concrete implementation that all other custom request handlers will probably want to extend - org.ringside.client.BaseRequestHandler. This class will provide the implementation to encode the parameters, add the necessary internal parameters needed by the Ringside server (such as "v" and "call_id"), add the MD5 signature and connect to the Ringside Server via the appropriate protocol (using an HTTP proxy if configured to do so).

Response Handlers

The Java client can process responses from a Ringside REST server invocation via response handlers. Their are response handler implementations that can return the REST XML responses as raw Strings, as XML represented by DOM Document elements and as Java POJOs generated by JAXB.

JAXB and XML Schema

The Java client supports processing API responses via JAXB (see JaxbResponseHandler). This requires an XML Schema, so the JAXB tools can generate the proper JAXB POJO classes. Currently, there is an M3 XML Schema that defines the responses that the M3 REST APIs will return. This allows M3JaxbResponseHandler to create a JAXB context that can handle responses from M3 API requests.

If you want the Java client to return JAXB objects for your own custom APIs, you need to write an XML Schema, put the .xsd in the src/main/resources folder and build the project via Maven. This will generate your JAXB classes for you. Once that occurs, you will have your JAXB classes in your project's classpath for handlers and clients to be able to use.

In the future, we may produce JAXB objects for the Ringside API as well as the Facebook API.