com.attachmate.connectors
Interface IConnectorAccess

public interface IConnectorAccess

This interface is the primary means of communication with connectors. The interface itself is generic, meaning that it does not make assumptions about the connector implementation, type of data being accessed or any communications or transport mechanisms.

A general synchronous scenario would be something like:

• Client calls open() and passes the unique identifier (e.g. URL, FileName, etc.) of a document containing a group of tasks and optional metadata about the tasks. If metadata is provided then all inputs and outputs must abide by the metadata.
• Connector retrieves the task document.
• Client calls getMetaData() to find out what tasks are available and what they "look" like.
• Connector returns meatadata as an xml string.
• Client sets the timeOut and maxSize properties if needed.
• Client calls execute() and specifies a task and the input data to execute with.
• Connector retrieves task data and initiates the task, returning when done.
• Client loops and calls getData to retrieve the results and check the available property to see if more data is left.
• Connector returns up to maxSize of retrieved data and sets the available property to the size of any remaing data.
• Client calls close() when done.
• Connector releases resouces as needed.

Method Summary

void	cancel() If execute() was successful, then cancel will attempt to abort the task.
void	close() Releases all resources.
void	execute(java.lang.String taskID, java.lang.String inputs) Excute the task identified by the taskID using the specified inputs.
int	getAvailable() Returns the amount of data left after a successful call to execute.
java.lang.String	getData() If execute() was successful, then getData returns XML containing the retrieved data.
int	getMaxSize() Returns the maxSize property.
java.lang.String	getMetaData(java.lang.String taskID) Returns the metadata for the specified task.
int	getTimeOut() Returns the timeOut property.
java.lang.String	open(java.lang.String path) Initializes the connector.
void	setMaxSize(int size) Sets the maxSize property.
void	setTimeOut(int time) Sets the timeOut property.

Method Detail

open

public java.lang.String open(java.lang.String path)
                      throws com.attachmate.connectors.ConnectorAccessException

Initializes the connector. Must be successfully called prior to calling execute()

Returns:

Returns the version of the data references by the path argument

Throws:

com.attachmate.connectors.ConnectorAccessException

execute

public void execute(java.lang.String taskID,
                    java.lang.String inputs)
             throws com.attachmate.connectors.ConnectorAccessException

Excute the task identified by the taskID using the specified inputs.
If successful, call getData() to retrieve results.

Parameters:

taskID - correlates to a named serialized task

inputs - String containing the inputs needed to accomplish specified task. The inputs must match the metadata if provided.

Throws:

com.attachmate.connectors.ConnectorAccessException

cancel

public void cancel()

If execute() was successful, then cancel will attempt to abort the task.
If the task is already complete, the retrieved data will be discarded.

getData

public java.lang.String getData()
                         throws com.attachmate.connectors.ConnectorAccessException

If execute() was successful, then getData returns XML containing the retrieved data.
The maximum amount of data that may be returned is specified by maxSize()
To determine if more data is available, call getAvailable().

Returns:

Returns an XML string containing requested data. Use getMetaData to get the details of the XML data format.

Throws:

com.attachmate.connectors.ConnectorAccessException

close

public void close()
           throws com.attachmate.connectors.ConnectorAccessException

Releases all resources. After close has been called, open() must be called again prior to executing another task.

Throws:

com.attachmate.connectors.ConnectorAccessException

getMetaData

public java.lang.String getMetaData(java.lang.String taskID)
                             throws com.attachmate.connectors.ConnectorAccessException

Returns the metadata for the specified task. open() must be called before the metadata will be available.

Parameters:

taskID - indicates the specific task. If "-1", then metadata for all tasks is returned.

Returns:

An XML string containing the task metadata

Throws:

com.attachmate.connectors.ConnectorAccessException

getAvailable

public int getAvailable()

Returns the amount of data left after a successful call to execute.
The maximum amount of data that may be returned by any one call to getData() is specified by maxSize()

Returns:

The amount of data remaining.

getMaxSize

public int getMaxSize()

Returns the maxSize property. MaxSize is the maximum amount of data that may be returned by calling getData(). Less data may be returned.

Returns:

The value of the maxSize property. -1 indicates all the data will be returned on the next call to getData().

setMaxSize

public void setMaxSize(int size)

Sets the maxSize property. MaxSize is the maximum amount of data that may be returned by calling getData(). Less data may be returned.

Parameters:

size - new value for the maxSize property. -1 indicates all the data will be returned on the next call to getData().

getTimeOut

public int getTimeOut()

Returns the timeOut property. The default is -1, which indicates no time out. The execute() method will return after the timeout has expired regardless of how much data has been retrieved.

Returns:

timeout value in milliseconds.

setTimeOut

public void setTimeOut(int time)

Sets the timeOut property. The default is -1, which indicates no time out. The execute() method will return after the timeout has expired regardless of how much data has been retrieved.

Parameters:

time - new value for the timeOut property.