uk.org.ogsadai.client.toolkit.wsi
Class WSIDataService

java.lang.Object
  |
  +--uk.org.ogsadai.client.toolkit.wsi.WSIDataService
All Implemented Interfaces:
DAIService, DataService, DataTransport, Properties, Service
Direct Known Subclasses:
ConfigurableWSIDataService

public class WSIDataService
extends java.lang.Object
implements DataService

Client-side stub for an OGSA-DAI WSI data service.

Author:
The OGSA-DAI Team.

Field Summary
private static java.lang.String COPYRIGHT_NOTICE
          Copyright statement
private  SOAPCallFactory mCallFactory
          Factory for creating SOAPCall objects with the correct settings.
protected  ResourceID mResourceID
          Current data service resource
private  java.net.URL mServiceURL
          URL of the service
private  WSIDataTransport mTransport
          Data transport operations stub
 
Constructor Summary
WSIDataService(java.lang.String url)
          Construct a new data service stub for the service at the given URL.
WSIDataService(java.lang.String url, ResourceID resourceID)
          Construct a new data service stub for the service at the given URL and set up to communicate with a data service resource exposed by the service.
 
Method Summary
 void closeSession(Session session)
          Closes the given session.
 DataTransport createDataTransport(ResourceID resourceID, SessionStreamID stream)
          Creates a new data transport object configured for reading and writing from the specified session stream.
 Session createSession()
          Creates a new session for this service.
 ActivityMetaData getActivityMetaData(java.lang.String activityName)
          Gets the meta-data about a specific activity supported by a data service resource.
 java.lang.Object getBlock()
          Gets a single block of data from the output stream of a data service resource.
protected  SOAPCallFactory getCallFactory()
          Gets the call factory to use for creating new SOAPCall objects.
 DataResourceInfo getDataResourceInfo()
          Gets information on a data resource exposed by a data service resource.
 java.net.URL getDataTransportURL()
          Obtain the URL of the data service.
 java.lang.Object getFully()
          Gets an entire data set from the output stream of a data service resource in one go.
 java.lang.Object getNBlocks(int numberOfBlocks)
          Gets an number of blocks of data from the output stream of a data service resource in one go.
 Property[] getProperties(javax.xml.namespace.QName[] names)
          Obtain multiple properties of a resource.
 Property getProperty(javax.xml.namespace.QName propertyName)
          Obtain a property of a resource.
 ResourceID getResourceID()
          Get the ID of the current data service resource.
 ResourceID[] getResourceIDs()
          Obtain the resource IDs of the resources that are exposed by this service.
private  java.lang.String getServiceURL(ResourceID resourceID)
          Generates the service URL from a resource ID.
 SessionStreamID getSessionStreamID()
          Gets the session stream ID - the session and stream of that session exposed by the data service resource of interest.
 RequestStatus getStatus(SessionID sessionID)
          Gets the request status of a request executing within a specific session.
 java.lang.String[] getSupportedActivities()
          Gets the names of the activities supported by a data service resource.
 java.net.URL getURL()
          Obtain the URL of the service
 DAIVersion getVersion()
          Get information on the OGSA-DAI distribution used to deploy the service.
 Response perform(Request request)
          Send a request to a data service resource exposed by a service.
 Response perform(RequestComponent component)
          Send a single activity request to a data service resource exposed by a service.
 void ping()
          Contacts the service to check it is running.
private  void pollUntilRequestCompleted(ResourceID resourceID, SessionID sessionID, int pollInterval, int timeoutPeriod, boolean forever)
           
 void pollUntilRequestCompleted(SessionID sessionID, int pollInterval)
          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'.
 void pollUntilRequestCompleted(SessionID sessionID, int pollInterval, int timeoutPeriod)
          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'.
 void putBlock(java.lang.Object data)
          Puts one block of data onto a data service resource input stream.
 void putClosingBlock()
          Inform a data service resource that it can close an input stream as all data has been forwarded.
 void putFully(java.lang.Object data)
          Puts an entire data set onto a data service resource input stream in one go.
 void setConnectionProperty(ConnectionProperty property)
          Configure the connection with a property.
 void setResourceID(ResourceID id)
          Set the ID of the current data service resource.
 void setSessionStreamID(SessionStreamID streamID)
          Sets the session stream ID - the session and stream of that session exposed by the data service resource of interest.
 void terminate()
          Send a request termination to a data service resource exposed by a service.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COPYRIGHT_NOTICE

private static final java.lang.String COPYRIGHT_NOTICE
Copyright statement

See Also:
Constant Field Values

mServiceURL

private final java.net.URL mServiceURL
URL of the service


mTransport

private WSIDataTransport mTransport
Data transport operations stub


mResourceID

protected ResourceID mResourceID
Current data service resource


mCallFactory

private final SOAPCallFactory mCallFactory
Factory for creating SOAPCall objects with the correct settings.

Constructor Detail

WSIDataService

public WSIDataService(java.lang.String url)
               throws java.net.MalformedURLException
Construct a new data service stub for the service at the given URL.

Parameters:
url - Data service URL.
Throws:
java.net.MalformedURLException - If the URL is malformed.

WSIDataService

public WSIDataService(java.lang.String url,
                      ResourceID resourceID)
               throws java.net.MalformedURLException
Construct a new data service stub for the service at the given URL and set up to communicate with a data service resource exposed by the service.

Parameters:
url - Data service URL.
resourceID - Data service resource name - may be null
Throws:
java.net.MalformedURLException - If the URL is malformed.
Method Detail

getCallFactory

protected SOAPCallFactory getCallFactory()
Gets the call factory to use for creating new SOAPCall objects.

Returns:
a SOAPCallFactory

perform

public Response perform(Request request)
                 throws ServerException,
                        AuthorisationException,
                        RequestException,
                        ResourceUnknownException,
                        ResourceBusyException,
                        ServiceCommsException
Description copied from interface: DataService
Send a request to a data service resource exposed by a service. The resource will attempt to process the request and send a response.

Specified by:
perform in interface DataService
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:
ResourceBusyException - If the requested resource is too busy to perform the request.
RequestException - If there is a problem with the client's request.
ServiceCommsException - If there was an error communicating with the service.
ServerException - If there was an error server-side.
ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.
AuthorisationException - If the client is not authorised to perform their request.

perform

public Response perform(RequestComponent component)
                 throws ServerException,
                        AuthorisationException,
                        RequestException,
                        ResourceUnknownException,
                        ResourceBusyException,
                        ServiceCommsException
Description copied from interface: DataService
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}))

Specified by:
perform in interface DataService
Parameters:
component - 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:
AuthorisationException - If the client is not authorised to perform their request.
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.
RequestException - If there is a problem with the client's request.
ServerException - If there was an error server-side.

terminate

public void terminate()
               throws ServerException,
                      AuthorisationException,
                      ResourceUnknownException,
                      ResourceBusyException,
                      ServiceCommsException
Description copied from interface: DataService
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

Specified by:
terminate in interface DataService
Throws:
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.
ServerException - If there was an error server-side.
ResourceBusyException - If the requested resource is too busy to perform the request.
AuthorisationException - If the client is not authorised to perform their request.

pollUntilRequestCompleted

public void pollUntilRequestCompleted(SessionID sessionID,
                                      int pollInterval)
                               throws ServiceCommsException,
                                      UnknownPropertyException,
                                      ResourceUnknownException,
                                      ServerException,
                                      AuthorisationException,
                                      RequestStatusException,
                                      java.lang.IllegalArgumentException
Description copied from interface: DataService
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.

Specified by:
pollUntilRequestCompleted in interface DataService
Parameters:
sessionID - Session identifier.
pollInterval - Time (in milliseconds) between polls.
Throws:
RequestStatusException - if the status shows that the request is not progressing smoothly.
ServerException - If there was an error server-side.
ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.
AuthorisationException - If the client is not authorised to perform their request.
java.lang.IllegalArgumentException - if sessionID is null or if the poll interval less than or equal to 0.
UnknownPropertyException - If the resource property that holds the request status is unknown to the resource.
ServiceCommsException - If there was an error communicating with the service.

pollUntilRequestCompleted

private void pollUntilRequestCompleted(ResourceID resourceID,
                                       SessionID sessionID,
                                       int pollInterval,
                                       int timeoutPeriod,
                                       boolean forever)
                                throws ServiceCommsException,
                                       UnknownPropertyException,
                                       ResourceUnknownException,
                                       ServerException,
                                       AuthorisationException,
                                       RequestStatusException,
                                       java.lang.IllegalArgumentException
ServiceCommsException
UnknownPropertyException
ResourceUnknownException
ServerException
AuthorisationException
RequestStatusException
java.lang.IllegalArgumentException

pollUntilRequestCompleted

public void pollUntilRequestCompleted(SessionID sessionID,
                                      int pollInterval,
                                      int timeoutPeriod)
                               throws ServiceCommsException,
                                      UnknownPropertyException,
                                      ResourceUnknownException,
                                      ServerException,
                                      AuthorisationException,
                                      RequestStatusException,
                                      java.lang.IllegalArgumentException
Description copied from interface: DataService
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.

Specified by:
pollUntilRequestCompleted in interface DataService
Parameters:
sessionID - Session identifier.
pollInterval - Time (in milliseconds) between polls.
timeoutPeriod - Time (in millisconds) to wait before giving up.
Throws:
ServerException - If there was an error server-side.
ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.
ServiceCommsException - If there was an error communicating with the service.
RequestStatusException - if the status shows that the request is not progressing smoothly.
UnknownPropertyException - If the resource property that holds the request status is unknown to the resource.
java.lang.IllegalArgumentException - if sessionID is null or if the poll interval less than or equal to 0.
AuthorisationException - If the client is not authorised to perform their request.

getStatus

public RequestStatus getStatus(SessionID sessionID)
                        throws ServiceCommsException,
                               UnknownPropertyException,
                               ResourceUnknownException,
                               ServerException,
                               AuthorisationException
Description copied from interface: DataService
Gets the request status of a request executing within a specific session.

Specified by:
getStatus in interface DataService
Parameters:
sessionID - Session identifier
Returns:
the session request status.
Throws:
ServiceCommsException - If there was an error communicating with the service.
AuthorisationException - If the client is not authorised to perform their request.
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.
ServerException - If there was an error server-side.

getDataResourceInfo

public DataResourceInfo getDataResourceInfo()
                                     throws ServiceCommsException,
                                            UnknownPropertyException,
                                            ResourceUnknownException,
                                            ServerException,
                                            AuthorisationException
Description copied from interface: DataService
Gets information on a data resource exposed by a data service resource.

Specified by:
getDataResourceInfo in interface DataService
Returns:
data resource information.
Throws:
ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.
AuthorisationException - If the client is not authorised to perform their request.
UnknownPropertyException - If the resource property that holds the data resource information is unknown to the resource.
ServerException - If there was an error server-side.
ServiceCommsException - If there was an error communicating with the service.

getSupportedActivities

public java.lang.String[] getSupportedActivities()
                                          throws ServiceCommsException,
                                                 UnknownPropertyException,
                                                 ResourceUnknownException,
                                                 ServerException,
                                                 AuthorisationException
Description copied from interface: DataService
Gets the names of the activities supported by a data service resource.

Specified by:
getSupportedActivities in interface DataService
Returns:
activity names.
Throws:
AuthorisationException - If the client is not authorised to perform their request.
ResourceUnknownException - If the resource at which the request is targetted is unknown to the service.
ServiceCommsException - If there was an error communicating with the service.
UnknownPropertyException - If the resource property that holds the activity information is unknown to the resource.
ServerException - If there was an error server-side.

getActivityMetaData

public ActivityMetaData getActivityMetaData(java.lang.String activityName)
                                     throws ServiceCommsException,
                                            UnknownPropertyException,
                                            ResourceUnknownException,
                                            ServerException,
                                            AuthorisationException
Description copied from interface: DataService
Gets the meta-data about a specific activity supported by a data service resource.

Specified by:
getActivityMetaData in interface DataService
Parameters:
activityName - Name of an activity.
Returns:
activity meta-data.
Throws:
ServerException - If there was an error server-side.
UnknownPropertyException - If the resource property that holds the activity information is unknown to the resource.
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.
AuthorisationException - If the client is not authorised to perform their request.

getProperty

public Property getProperty(javax.xml.namespace.QName propertyName)
                     throws UnknownPropertyException,
                            ResourceUnknownException,
                            AuthorisationException,
                            ServiceCommsException,
                            ServerException
Description copied from interface: Properties
Obtain a property of a resource.

Specified by:
getProperty in interface Properties
Parameters:
propertyName - Qualified name of the property
Returns:
property
Throws:
UnknownPropertyException - If the property is unknown to the resource.
ResourceUnknownException - If the resource is unknown to the service.
ServiceCommsException - If there was an error communicating with the service.
ServerException - If there was an error server-side.
AuthorisationException - If the client is not authorised to access this information.

getProperties

public Property[] getProperties(javax.xml.namespace.QName[] names)
                         throws UnknownPropertyException,
                                ResourceUnknownException,
                                AuthorisationException,
                                ServiceCommsException,
                                ServerException
Description copied from interface: Properties
Obtain multiple properties of a resource.

Specified by:
getProperties in interface Properties
Parameters:
names - An array of qualified names of the properties.
Returns:
array of properties.
Throws:
ServiceCommsException - If there was an error communicating with the service.
AuthorisationException - If the client is not authorised to access this information.
UnknownPropertyException - If one of the properties is unknown to the resource.
ServerException - If there was an error server-side.
ResourceUnknownException - If the resource is unknown to the service.

getVersion

public DAIVersion getVersion()
                      throws ServiceCommsException,
                             ServerException
Description copied from interface: DAIService
Get information on the OGSA-DAI distribution used to deploy the service.

Specified by:
getVersion in interface DAIService
Returns:
version information.
Throws:
ServerException - If there was an error server-side.
ServiceCommsException - If there was an error communicating with the service.

getURL

public java.net.URL getURL()
Description copied from interface: Service
Obtain the URL of the service

Specified by:
getURL in interface Service
Returns:
the URL

getResourceIDs

public ResourceID[] getResourceIDs()
                            throws ServiceCommsException,
                                   ServerException
Description copied from interface: Service
Obtain the resource IDs of the resources that are exposed by this service.

Specified by:
getResourceIDs in interface Service
Returns:
an array of resource IDs
Throws:
ServiceCommsException - If there was an error communicating with the service.
ServerException - If there was an error server-side.

setConnectionProperty

public void setConnectionProperty(ConnectionProperty property)
Description copied from interface: DataTransport
Configure the connection with a property.

Specified by:
setConnectionProperty in interface Service
Parameters:
property - A connection property

getFully

public java.lang.Object getFully()
                          throws ServerException,
                                 AuthorisationException,
                                 RequestException,
                                 ResourceUnknownException,
                                 ResourceBusyException,
                                 ServiceCommsException
Description copied from interface: DataTransport
Gets an entire data set from the output stream of a data service resource in one go.

Specified by:
getFully in interface DataTransport
Returns:
entire data set
Throws:
ResourceUnknownException - If the resource is unknown to the service.
ResourceBusyException - If the resource is busy.
RequestException - If there is a problem with the client's request e.g there is no such session.
AuthorisationException - If the client is not authorised to access the service, resource, session or stream.
ServiceCommsException - If there was an error communicating with the service.
ServerException - If there was an error server-side.

getNBlocks

public java.lang.Object getNBlocks(int numberOfBlocks)
                            throws ServerException,
                                   AuthorisationException,
                                   RequestException,
                                   ResourceUnknownException,
                                   ResourceBusyException,
                                   ServiceCommsException
Description copied from interface: DataTransport
Gets an number of blocks of data from the output stream of a data service resource in one go. The blocks are aggregated to form a single larger block.

Specified by:
getNBlocks in interface DataTransport
Parameters:
numberOfBlocks - Number of blocks to get.
Returns:
the aggregated block of data retrieved or ServiceConstants.NO_MORE_DATA if there is no more data to retrieve.
Throws:
RequestException - If there is a problem with the client's request e.g there is no such session.
ResourceUnknownException - If the resource is unknown to the service.
ServerException - If there was an error server-side.
ServiceCommsException - If there was an error communicating with the service.
AuthorisationException - If the client is not authorised to access the service, resource, session or stream.
ResourceBusyException - If the resource is busy.

getBlock

public java.lang.Object getBlock()
                          throws ServerException,
                                 AuthorisationException,
                                 RequestException,
                                 ResourceUnknownException,
                                 ResourceBusyException,
                                 ServiceCommsException
Description copied from interface: DataTransport
Gets a single block of data from the output stream of a data service resource.

Specified by:
getBlock in interface DataTransport
Returns:
the block of data retrieved or ServiceConstants.NO_MORE_DATA if there is no more data to retrieve.
Throws:
AuthorisationException - If the client is not authorised to access the service, resource, session or stream.
ResourceUnknownException - If the resource is unknown to the service.
RequestException - If there is a problem with the client's request e.g there is no such session.
ServiceCommsException - If there was an error communicating with the service.
ServerException - If there was an error server-side.
ResourceBusyException - If the resource is busy.

putFully

public void putFully(java.lang.Object data)
              throws ServerException,
                     AuthorisationException,
                     RequestException,
                     ResourceUnknownException,
                     ResourceBusyException,
                     ServiceCommsException
Description copied from interface: DataTransport
Puts an entire data set onto a data service resource input stream in one go.

Specified by:
putFully in interface DataTransport
Parameters:
data - The complete set of data.
Throws:
ServiceCommsException - If there was an error communicating with the service.
ResourceUnknownException - If the resource is unknown to the service.
RequestException - if there is a problem with the client's request e.g there is no such session.
AuthorisationException - If the client is not authorised to access the service, resource, session or stream.
ServerException - If there was an error server-side.
ResourceBusyException - if the resource is busy.

putBlock

public void putBlock(java.lang.Object data)
              throws ServerException,
                     AuthorisationException,
                     RequestException,
                     ResourceUnknownException,
                     ResourceBusyException,
                     ServiceCommsException
Description copied from interface: DataTransport
Puts one block of data onto a data service resource input stream. Once all blocks have been submitted using this method, the putClosingBlock method should be called to signal to the data service resource that all the data has been forwarded.

Specified by:
putBlock in interface DataTransport
Parameters:
data - Block of data.
Throws:
ServerException - If there was an error server-side.
AuthorisationException - If the client is not authorised to access the service, resource, session or stream.
ResourceBusyException - if the resource is busy.
ResourceUnknownException - If the resource is unknown to the service.
ServiceCommsException - If there was an error communicating with the service.
RequestException - if there is a problem with the client's request e.g there is no such session.

putClosingBlock

public void putClosingBlock()
                     throws ServerException,
                            AuthorisationException,
                            RequestException,
                            ResourceUnknownException,
                            ResourceBusyException,
                            ServiceCommsException
Description copied from interface: DataTransport
Inform a data service resource that it can close an input stream as all data has been forwarded. After a call to this method the putBlock method should no longer be called.

Specified by:
putClosingBlock in interface DataTransport
Throws:
ResourceBusyException - if the resource is busy.
ServerException - If there was an error server-side.
ResourceUnknownException - If the resource is unknown to the service.
AuthorisationException - If the client is not authorised to access the service, resource, session or stream.
ServiceCommsException - If there was an error communicating with the service.
RequestException - if there is a problem with the client's request e.g there is no such session.

getDataTransportURL

public java.net.URL getDataTransportURL()
Description copied from interface: DataTransport
Obtain the URL of the data service.

Specified by:
getDataTransportURL in interface DataTransport
Returns:
URL

getResourceID

public ResourceID getResourceID()
Get the ID of the current data service resource.

Specified by:
getResourceID in interface DataTransport
Returns:
resource ID

setResourceID

public void setResourceID(ResourceID id)
Set the ID of the current data service resource.

Specified by:
setResourceID in interface Service
Parameters:
id - Resource ID.

getSessionStreamID

public SessionStreamID getSessionStreamID()
Description copied from interface: DataTransport
Gets the session stream ID - the session and stream of that session exposed by the data service resource of interest.

Specified by:
getSessionStreamID in interface DataTransport
Returns:
session stream ID

setSessionStreamID

public void setSessionStreamID(SessionStreamID streamID)
Description copied from interface: DataTransport
Sets the session stream ID - the session and stream of that session exposed by the data service resource of interest.

Specified by:
setSessionStreamID in interface DataTransport
Parameters:
streamID - Session stream identifier

createSession

public Session createSession()
                      throws ServerException,
                             AuthorisationException,
                             RequestException,
                             ResourceUnknownException,
                             ResourceBusyException,
                             ServiceCommsException
Description copied from interface: DataService
Creates a new session for this service.

Specified by:
createSession in interface DataService
Returns:
a session that has been created
Throws:
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.
RequestException - If there is a problem with the client's request.
AuthorisationException - If the client is not authorised to perform their request.
ResourceBusyException - If the requested resource is too busy to perform the request.
ServerException - If there was an error server-side.

closeSession

public void closeSession(Session session)
                  throws ServerException,
                         AuthorisationException,
                         RequestException,
                         ResourceUnknownException,
                         ResourceBusyException,
                         ServiceCommsException
Description copied from interface: DataService
Closes the given session.

Specified by:
closeSession in interface DataService
Parameters:
session - the session to be closed
Throws:
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.
ServerException - If there was an error server-side.
ResourceBusyException - If the requested resource is too busy to perform the request.
RequestException - If there is a problem with the client's request.
AuthorisationException - If the client is not authorised to perform their request.

ping

public void ping()
          throws ServiceCommsException
Description copied from interface: Service
Contacts the service to check it is running.

Specified by:
ping in interface Service
Throws:
ServiceCommsException - If there was an error communicating with the service.

createDataTransport

public DataTransport createDataTransport(ResourceID resourceID,
                                         SessionStreamID stream)
Description copied from interface: DataService
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.

Specified by:
createDataTransport in interface DataService
Parameters:
resourceID - data service resource identifier
stream - session stream identifier
Returns:
a new DataTransport object

getServiceURL

private java.lang.String getServiceURL(ResourceID resourceID)
Generates the service URL from a resource ID.

Parameters:
resourceID - Resource ID
Returns:
service URL of form ServiceURL/DAIid.getName()