uk.org.ogsadai.client.toolkit.service
Interface DataService

All Superinterfaces:

DAIService, DataTransport, Properties, Service

All Known Subinterfaces:

ConfigurableDataService

All Known Implementing Classes:

ConfigurableWSIDataService, ConfigurableWSRFDataService, WSIDataService, WSRFDataService

public interface DataService

extends DAIService, DataTransport

Interface for data service proxies that provides standard operations of a data service.

Author:

The OGSA-DAI Project Team

perform

public Response perform(Request request)
                 throws ServerException,
                        AuthorisationException,
                        RequestException,
                        ResourceUnknownException,
                        ResourceBusyException,
                        ServiceCommsException

Send a request to a data service resource exposed by a service. The resource will attempt to process the request and send a response.

Parameters:

request - Request specifying the work to be performed by a data service resource.

Returns:

Response from the data service resource containing the status of the request and any output results.

Throws:

RequestException - If there is a problem with the client's request.

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

ResourceBusyException - If the requested resource is too busy to perform the request.

java.lang.IllegalArgumentException - if request is null.

terminate

public void terminate()
               throws ServerException,
                      AuthorisationException,
                      ResourceUnknownException,
                      ResourceBusyException,
                      ServiceCommsException

Send a request termination to a data service resource exposed by a service. The resource will attempt to terminate the request and send a response. Services do not implement this operation at present

Throws:

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

ResourceBusyException - If the requested resource is too busy to perform the request.

perform

public Response perform(RequestComponent request)
                 throws ServerException,
                        AuthorisationException,
                        RequestException,
                        ResourceUnknownException,
                        ResourceBusyException,
                        ServiceCommsException

Send a single activity request to a data service resource exposed by a service. The resource will attempt to process the request and send a response.

This is a shortcut when the request consists of only one activity. It is functionally equivalent to:
perform(new ActivityRequest(new Activity[]{activity}))

Parameters:

request - RequestComponent specifying the work to be performed by a data service resource.

Returns:

Response from the data service resource containing the status of the request and any output results.

Throws:

RequestException - If there is a problem with the client's request.

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

ResourceBusyException - If the requested resource is too busy to perform the request.

java.lang.IllegalArgumentException - if request is null.

createSession

public Session createSession()
                      throws ServerException,
                             AuthorisationException,
                             RequestException,
                             ResourceUnknownException,
                             ResourceBusyException,
                             ServiceCommsException

Creates a new session for this service.

Returns:

a session that has been created

Throws:

ServiceCommsException - If there was an error communicating with the service.

ResourceBusyException - If the requested resource is too busy to perform the request.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

RequestException - If there is a problem with the client's request.

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

closeSession

public void closeSession(Session session)
                  throws ServerException,
                         AuthorisationException,
                         RequestException,
                         ResourceUnknownException,
                         ResourceBusyException,
                         ServiceCommsException

Closes the given session.

Parameters:

session - the session to be closed

Throws:

ServiceCommsException - If there was an error communicating with the service.

ResourceBusyException - If the requested resource is too busy to perform the request.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

RequestException - If there is a problem with the client's request.

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

getStatus

public RequestStatus getStatus(SessionID sessionID)
                        throws ServiceCommsException,
                               UnknownPropertyException,
                               ResourceUnknownException,
                               ServerException,
                               AuthorisationException

Gets the request status of a request executing within a specific session.

Parameters:

sessionID - Session identifier

Returns:

the session request status.

Throws:

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

UnknownPropertyException - If the resource property that holds the request status is unknown to the resource.

java.lang.IllegalArgumentException - if sessionID is null.

pollUntilRequestCompleted

public void pollUntilRequestCompleted(SessionID sessionID,
                                      int pollInterval)
                               throws ServiceCommsException,
                                      UnknownPropertyException,
                                      ResourceUnknownException,
                                      ServerException,
                                      AuthorisationException,
                                      RequestStatusException

Polls a data service resource exposed by a data service for the request status for a specific session and blocks until the status is 'COMPLETED'.

If at any time the status indicates that the request is not progressing smoothly a RequestStatusException is thrown.

Parameters:

sessionID - Session identifier.

pollInterval - Time (in milliseconds) between polls.

Throws:

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

UnknownPropertyException - If the resource property that holds the request status is unknown to the resource.

RequestStatusException - if the status shows that the request is not progressing smoothly.

java.lang.IllegalArgumentException - if sessionID is null or if the poll interval less than or equal to 0.

pollUntilRequestCompleted

public void pollUntilRequestCompleted(SessionID sessionID,
                                      int pollInterval,
                                      int timeoutPeriod)
                               throws ServiceCommsException,
                                      UnknownPropertyException,
                                      ResourceUnknownException,
                                      ServerException,
                                      AuthorisationException,
                                      RequestStatusException,
                                      java.lang.IllegalArgumentException

Polls a data service resource exposed by a data service for the request status for a specific session and blocks until the status is 'COMPLETED'.

If at any time the status indicates that the request is not progressing smoothly a RequestStatusException is thrown.

If the status has not reached 'COMPLETED' within the specififed timeout period a RequestStatusException is thrown.

This method does not timeout. It will only terminate when the status shows the request has completed or in error, or when an error occurs contacting the service.

Parameters:

sessionID - Session identifier.

pollInterval - Time (in milliseconds) between polls.

timeoutPeriod - Time (in millisconds) to wait before giving up.

Throws:

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

UnknownPropertyException - If the resource property that holds the request status is unknown to the resource.

RequestStatusException - if the status shows that the request is not progressing smoothly.

java.lang.IllegalArgumentException - if sessionID is null or if the poll interval less than or equal to 0.

getDataResourceInfo

public DataResourceInfo getDataResourceInfo()
                                     throws ServiceCommsException,
                                            UnknownPropertyException,
                                            ResourceUnknownException,
                                            ServerException,
                                            AuthorisationException

Gets information on a data resource exposed by a data service resource.

Returns:

data resource information.

Throws:

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

UnknownPropertyException - If the resource property that holds the data resource information is unknown to the resource.

getSupportedActivities

public java.lang.String[] getSupportedActivities()
                                          throws ServiceCommsException,
                                                 UnknownPropertyException,
                                                 ResourceUnknownException,
                                                 ServerException,
                                                 AuthorisationException

Gets the names of the activities supported by a data service resource.

Returns:

activity names.

Throws:

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

UnknownPropertyException - If the resource property that holds the activity information is unknown to the resource.

getActivityMetaData

public ActivityMetaData getActivityMetaData(java.lang.String activityName)
                                     throws ServiceCommsException,
                                            UnknownPropertyException,
                                            ResourceUnknownException,
                                            ServerException,
                                            AuthorisationException

Gets the meta-data about a specific activity supported by a data service resource.

Parameters:

activityName - Name of an activity.

Returns:

activity meta-data.

Throws:

AuthorisationException - If the client is not authorised to perform their request.

ServerException - If there was an error server-side.

ServiceCommsException - If there was an error communicating with the service.

ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.

UnknownPropertyException - If the resource property that holds the activity information is unknown to the resource.

java.lang.IllegalArgumentException - if activityName is null.

createDataTransport

public DataTransport createDataTransport(ResourceID resourceID,
                                         SessionStreamID stream)

Creates a new data transport object configured for reading and writing from the specified session stream. The initial connection properties used to communicate with the stream are inherited from this data service, but can be changed independently afterwards.

Parameters:

resourceID - data service resource identifier

stream - session stream identifier

Returns:

a new DataTransport object