Creating a Connector

To use the connector first create an instance explaining which type of chain you wish to use. There are currently two types of chains that can be used by the client, the standard and the dummy.

The standard chain is the one to be used in real works that need to connect to an existing server and services which must have been implemented.

The dummy chain allows for fast start up and testing while the server side is being built, it reads the service responses from file. In fact this second chain tries to find a file with its name being that of the service name required to execute. It then returns that file as the response body. Dummy chain does no check on registered services, it only expects to find the file declared at the request service name

To create an instance of the connector:

					try {
						connector = new	ARESTConnector(ConnectorTypes.STANDARD);
					} catch (final ConfigurationException e) {
						LOGGER.error(e);
					} catch (final Exception e) {
						LOGGER.error(e);
					}
				

make sure you do something with the configuration exceptions since the client won't be able to autocorrect itself.

Make sure you execute connector.shutdown() when all work with the connector is done and you have no further use of the connector.
NOTE:
The connector can be stored in the application context in order to allow faster connections in a web application but you need to make sure it is destroyed when the application context is destroyed, the connector.shutdown() must be called.

Creating Requests

A request must be created to serve it with the connector.

					ConnectorRequest request = new StandardConnectorRequest("downloadFile", myParams);
				

The name of the service and a Map of parameters is expected to create the request. The parameters map can be any type of java.util.map with String,Object type parameters

					final Map<String, Object> myParams = new HashMap<String, Object>();
					myParams.put("store_type", "workspace");
					myParams.put("store_id", "SpacesStore");
					myParams.put("id", "fe424d83-d697-401c-b29e-ce1a915d7283");
				

It is important to remember that all parameters declared in the services.xml for the called service must be present in the parameters' map though they do not all need to have a value.

Parameters can be of any object and that includes files and streams but you need to be careful of the kind of service and the methods you use to pass those parameters over to the server. e.g. Files can be passed with a multi POST request not with a GET

Single files can be uploaded to the server with a put request in which case the body of the request must contain the file:

					ConnectorRequest request = new StandardConnectorRequest("uploadFile", myParams);
					request.setBody(myCreation);
				

Serving requests

Servicing a request is a simple as :ConnectorResponse resp= connector.serve(request);

It is important to collect the response since you will get no other chance to retrieve any errors occuring. Be sure though to enclose the serve code in a try catch for any CommandExceptions that will occure due to missconfiguration or wrong parameters pass. Also, do NOT alter the request after it is sent to the connector or you may face execution problems. In a multithreaded environment, do not reuse the created request, built a new one.

Retrieving results

A quick look to resp.hasErrors() in the response will allow you to determine if there was an error during serving the request. The resp.getErrors() will return a list of ARESTCError objects with error code, description and the service that provoked them.resp.getBody() allows you access to the bulk of response from the server and resp.getResponseHeaders() provides access to the headers of that response

Make sure you release the connection after all is done: response.releaseConnection()