*** This interface provides Binary Compatibility only, not Source Compatibility ***

com.sas.services.storedprocess
Interface StoredProcessInterface

All Superinterfaces:

com.sas.entities.EntityKeyInterface, java.rmi.Remote, com.sas.entities.RemoteBaseEntityInterface, com.sas.entities.RemoteBaseEntityValueInterface, com.sas.entities.RemoteEntityInterface, com.sas.RemoteObjectInterface, StoredProcessBaseInterface

Deprecated. Use StoredProcess2Interface instead.

public interface StoredProcessInterface
extends com.sas.entities.RemoteEntityInterface, com.sas.entities.EntityKeyInterface, StoredProcessBaseInterface

This is the original interface of the Stored Process service object. It inherits from com.sas.entities.RemoteEntityInterface and a good understanding of the various interfaces provided by com.sas.entities is important to fully exploit this interface. The interface only supports Stored Processes in the Version 0 metadata format.

Stored process objects are either created by the Information Service from metadata or manually by the user using methods provided by StoredProcessServiceInterface

If the stored process is created by the Information Service from metadata, setters cannot be used to modify most properties of the stored process. If a setter is invoked an IllegalStateException will be thrown - the doc on each setter describes whether this is applicable to the setter. If there are required parameters their values must be supplied and the service enforces this requirement.

If manually created, setters to set the file name, directory and connection must be invoked. If there are required parameters their values should be supplied. However, the service has no way of enforcing this requirement.

In version 9.2, Version 2 Stored Process service objects (StoredProcess2Interface) were introduced and methods common to both this interface and StoredProcess2Interface were moved to StoredProcessBaseInterface, which this interface now extends. There was no change to set of methods supported by this interface in this refactoring.

Since:

1.0

Field Summary

static int	RESULT_TYPE_NONE Deprecated. No package or stream is delivered by the stored process service.
static int	RESULT_TYPE_PERMANENT_FILE_PACKAGE Deprecated. A permanent package (with backing in the file system) is delivered by the stored process service.
static int	RESULT_TYPE_PERMANENT_WEBDAV_PACKAGE Deprecated. A permanent package (with WebDAV backing) is delivered by the stored process service.
static int	RESULT_TYPE_STREAM Deprecated. Results are delivered via one of more Streams.
static int	RESULT_TYPE_TRANSIENT_PACKAGE Deprecated. A transient package (with no backing) is delivered by the stored process service.

Fields inherited from interface com.sas.services.storedprocess.StoredProcessBaseInterface

SERVER_TYPE_STOREDPROCESS, SERVER_TYPE_WORKSPACE

Method Summary

boolean	addInputStream(java.lang.String streamKey) Deprecated. Adds an input stream definition to the stored process.
ExecutionInterface	execute(boolean synchronous, ExecutionStatusListenerInterface listener, boolean createAlert, java.lang.Object connection) Deprecated. Execute the stored process.
com.sas.entities.AttributeDescriptorInterface[]	getParameters() Deprecated. Get parameter descriptions.
ResultHints	getResultHintsInstance(int hintSubType) Deprecated. Get a ResultHints object for specifying result hints for this stored process.
int	getResultType() Deprecated. Gets the type of result.
boolean	isResultPackageReturned() Deprecated. Determines whether a package is returned.
void	setParameterValue(java.lang.String name, java.lang.Object value) Deprecated. Sets the value of the specified parameter.
void	setParameterValues(java.util.Map map) Deprecated. Sets the values of the specified parameters.
void	setResultHints(ResultHints resultHints) Deprecated. Set hints for the result of the stored process.
void	setResultType(int resultType) Deprecated. Sets the type of result.

Methods inherited from interface com.sas.services.storedprocess.StoredProcessBaseInterface

addOutputStream, destroy, getDescription, getDirectory, getFileName, getInputStreamNames, getName, getOutputStreamNames, getServer, getServerType, hasParameters, setDescription, setName, setPrivilegedUser, setSourceFromFile

Field Detail

RESULT_TYPE_NONE

static final int RESULT_TYPE_NONE

Deprecated.

No package or stream is delivered by the stored process service. Also see getResultType() and the newStoredProcess(SessionContextInterface, int, int) method of StoredProcessServiceInterface.

See Also:

Constant Field Values

RESULT_TYPE_TRANSIENT_PACKAGE

static final int RESULT_TYPE_TRANSIENT_PACKAGE

Deprecated.

A transient package (with no backing) is delivered by the stored process service. Also see getResultType() and the newStoredProcess(SessionContextInterface, int, int) method of StoredProcessServiceInterface.

See Also:

Constant Field Values

RESULT_TYPE_PERMANENT_FILE_PACKAGE

static final int RESULT_TYPE_PERMANENT_FILE_PACKAGE

Deprecated.

A permanent package (with backing in the file system) is delivered by the stored process service. Also see getResultType() and the newStoredProcess(SessionContextInterface, int, int) method of StoredProcessServiceInterface.

See Also:

Constant Field Values

RESULT_TYPE_PERMANENT_WEBDAV_PACKAGE

static final int RESULT_TYPE_PERMANENT_WEBDAV_PACKAGE

Deprecated.

A permanent package (with WebDAV backing) is delivered by the stored process service. Also see getResultType() and the newStoredProcess(SessionContextInterface, int, int) method of StoredProcessServiceInterface.

See Also:

Constant Field Values

RESULT_TYPE_STREAM

static final int RESULT_TYPE_STREAM

Deprecated.

Results are delivered via one of more Streams. Also see getResultType() and the newStoredProcess(SessionContextInterface, int, int) method of StoredProcessServiceInterface.

See Also:

Constant Field Values

Method Detail

execute

ExecutionInterface execute(boolean synchronous,
                           ExecutionStatusListenerInterface listener,
                           boolean createAlert,
                           java.lang.Object connection)
                           throws java.lang.IllegalStateException,
                                  ExecutionException,
                                  java.rmi.RemoteException

Deprecated.

Execute the stored process. A list of name-value pairs is created from the parameter list in the format expected by the server executing the stored process and is passed to the server. Results may be captured as an alert item in the Personal Repository.

Execution of the stored process can be synchronous or asynchronous. In the synchronous case the method blocks until execution is complete. In the asynchronous case the method returns and the stored process is executed in a separate thread.

In both the synchronous and asynchronous cases this method does some preliminary processing synchronously and there is the potential for exceptions being thrown in this processing. These exceptions are listed in the throws clause and may occur when:

• the parameter list is checked to ensure that all required parameters have values.
• a connection is made to the server.
• an alert is created (if requested).
• there is a problem determining the WebDAV location to which results are published. This can only occur if the result type is RESULT_TYPE_PERMANENT_WEBDAV_PACKAGE.

After the preliminary processing described above is done, an ExecutionInterface is created to capture the state of execution and provide access to results, and then execution proceeds synchronously or asynchronously as requested. The created ExecutionInterface is returned by this method. If there are any exceptions from this point onward, they can be obtained via ExecutionBaseInterface.getExceptions(). It is possible that multiple exceptions have occurred and the following is a list of specializations of ExecutionException that may be present in the list:

• AlertProcessingException
• ResultsBindingException
• ExecutionStatusListenerException
• SASServerException

Note: the execute() method may be called multiple times with different sets of parameters. On invocation all relevant information is copied before the method returns. Once the method returns the StoredProcessInterface object may be modified and execute() invoked again. Or, if there is no further use for the stored process object it may be destroyed.

Parameters:

synchronous - true: execute synchronously; false: execute asynchronously.

listener - specifies the listener that gets control when execution completes; can be null.

createAlert - true: capture results by creating an alert item; false: do not capture results.

connection - This argument should be null if the service is to obtain a connection. If a connection is supplied the following are valid argument types:

• String: id of the session in which the stored process is to be executed. This argument is specific to stored prcesses executing on StoredProcess servers and is used to execute the stored process in an existing session. If execution of a previous stored process resulted in the creation of a session, a subsequent stored process can use this method to connect to that session by specifying the sessionID of that session.
• ConnectionInterface: the underlying connection object should be appropriate to the type of server on which the stored process executes.
• IWorkspace: if the stored process executes on a Workspace server. The StoredProcess Service obtains the ILanguageService object from the client supplied IWorkspace. The client should not use the ILanguageService associated with the supplied IWorkspace during the execution of the stored process.
• IStoredProcessServer: if the stored process executes on a StoredProcess server.

Returns:

an ExecutionInterface object describing the state and the results of the execution. ExecutionInterface.getStatus() provides information about different completion codes generated by the execute() method.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException - if there is no session or user context or if destroy() has been called.

ExecutionException - or one of its specializations. The following specializations can be thrown

• AlertProcessingException - if there are problems creating and initializing the alert.
• SASServerException - possible wrapped exceptions are:
  • com.sas.iom.SASStoredProcess.IStoredProcessContextPackage.InvalidFileref - if the stream was not created as the name does not conform to the SAS fileref naming rules.
  • com.sas.iom.SASStoredProcess.IStoredProcessContextPackage.StreamFilerefFail - if the stream was not created due to a fileref assignment failure.
  • com.sas.iom.SASStoredProcess.IStoredProcessServerPackage.BadSessionID - if a session id that is unknown to the stp server or has expired was used.
• MissingParameterException - if a parameter that is required has not been assigned a value.
• InvalidParameterValueException - if the parameter value is invalid (additonal details in the InvalidParameterValueException javadoc).
• SessionNotFoundException - if the session was not found (additonal details in the SessionNotFoundException javadoc).
• SessionNotAvailableException - if the session was not available (additonal details in the SessionNotAvailableException javadoc).

If the super-class ExecutionException is thrown the following could be wrapped:

• ConnectionFactoryException - thrown by the Connection Service, which manages connections.
• IllegalServiceStateException - if there are various inconsistencies in the state of the Stored Process service.
• ServiceException - if there are problems accessing the Personal Repository.

In general, if a wrapped exception is present, it provides more specific information.

Also see ExecutionInterface.getStatus()

addInputStream

boolean addInputStream(java.lang.String streamKey)
                       throws java.rmi.RemoteException,
                              java.lang.IllegalStateException

Deprecated.

Adds an input stream definition to the stored process. The client reads from the input stream which provides a channel for the output of the stored process.

Input streams and output streams use the same fileref name space.

Specified by:

addInputStream in interface StoredProcessBaseInterface

Parameters:

streamKey - name of the input stream (must be a valid SAS fileref name) Stream names have the following restrictions:

• The length of the name must be no greater than 8 characters.
• The first character is either an English letter or an underscore.
• Subsequent characters can be English letters, underscores or digits.

Returns:

true if the name was not present; false if it was with the same options.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException -

• if called on a stored process created from metadata, unless setResultType(int) has been invoked
• if the name is not a valid SAS fileref name
• if the name has been specified before with a different set of options
• if the name has already been defined as an output stream
• if the server type is not StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS
• if destroy() has been called

getResultType

int getResultType()
                  throws java.rmi.RemoteException

Deprecated.

Gets the type of result. Returns one of the RESULT_TYPE_* values.

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

setResultType

void setResultType(int resultType)
                   throws java.lang.IllegalStateException,
                          java.rmi.RemoteException

Deprecated.

Sets the type of result. See newStoredProcess(SessionContextInterface, int, int) method of StoredProcessServiceInterface for a list of result types which are valid for this server type. The result type can be set to any of the other result types that are valid for the server. If the result type specified is the same as the current result type no changes are made. If the result type is changed, a subsequent call to getResultHintsInstance(int) will return a newly constructed ResultHints sub-classed object which is appropriate for the new result type. If result metadata associated with the old result type is desired, getResultHintsInstance(int) should be called before setResultType() is called.

Any streams that supply input to the stored process are not affected by this call.

If the result type is switched to RESULT_TYPE_STREAM, it is the responsibility of the client to add streams (see addInputStream(java.lang.String)) the stored process can output to. Also, if the result type is switched from RESULT_TYPE_STREAM the streams the stored process wrote output to (typically, one named "_WEBOUT") are deleted.

Parameters:

resultType - specifies the type of result.

Throws:

java.lang.IllegalStateException -

• if the result type is not appropriate for the type of server the stored process runs on
• if destroy() has been called

java.rmi.RemoteException - if a network anomaly is encountered.

isResultPackageReturned

boolean isResultPackageReturned()
                                throws java.rmi.RemoteException

Deprecated.

Determines whether a package is returned.

Returns:

true if a package is returned; false if not

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

setResultHints

void setResultHints(ResultHints resultHints)
                    throws ServiceException,
                           java.rmi.RemoteException

Deprecated.

Set hints for the result of the stored process. The only valid result types on which this method may be called are RESULT_TYPE_TRANSIENT_PACKAGE, RESULT_TYPE_PERMANENT_FILE_PACKAGE and RESULT_TYPE_PERMANENT_WEBDAV_PACKAGE in which cases the hint objects should be of types described in getResultHintsInstance(int).

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

ServiceException - if there is an error validating the hints specified. The text of the exception should provide additional information.

java.lang.IllegalStateException -

• if called on a stored process with a result type which does not support hints
• if destroy() has been called

getResultHintsInstance

ResultHints getResultHintsInstance(int hintSubType)
                                   throws java.rmi.RemoteException

Deprecated.

Get a ResultHints object for specifying result hints for this stored process. This method together with setResultHints() can be used to direct the output of a stored process to a location other than that already defined. Do note that this mechanism does not allow the type of the result (e.g., package to non-package) to be changed.

Hints objects are returned for all stored processes with one of the result package result types.

If a hints object is already associated with this stored process and it is of the same type as that requested, a clone of the object is returned. For stored processes created from metadata, the hints object is associated with the stored process when the stored process is created from metadata and reflects the type and location of the results; for manually created stored processes, a hints object is associated after a call to setResultHints() following a call to this method.

Parameters:

hintSubType - this depends on the type of the result specified when this stored process was created. For

• RESULT_TYPE_PERMANENT_WEBDAV_PACKAGE valid values are ResultHints.HINT_SUBTYPE_WEBDAV_USER_PR, ResultHints.HINT_SUBTYPE_WEBDAV_DAVSERVER and ResultHints.HINT_SUBTYPE_WEBDAV_URL.
• all other types the value supplied is ignored. If desired, ResultHints.HINT_SUBTYPE_NA may be used in such cases.

If hintSubType is set to ResultHints.HINT_SUBTYPE_SET, a clone of the associated hints object is returned.

Returns:

depends on the type of the result specified when this stored process was created:

• RESULT_TYPE_TRANSIENT_FILE_PACKAGE returns a TransientPackageResultHints
• RESULT_TYPE_PERMANENT_FILE_PACKAGE returns a PermanentPackageResultHints
• RESULT_TYPE_PERMANENT_WEBDAV_PACKAGE returns
  • a WebDAVPackageURLResultHints if hintSubType is ResultHints.HINT_SUBTYPE_WEBDAV_URL
  • a WebDAVPackageDAVServerResultHints if hintSubType is ResultHints.HINT_SUBTYPE_WEBDAV_DAVSERVER
  • a WebDAVPackagePRResultHints if hintSubType is ResultHints.HINT_SUBTYPE_WEBDAV_USER_PR

A null is returned for all other results types.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException - if the hintSubType is not appropriate for the resultType of the stored process created from metadata or destroy() has been called or hintSubType is ResultHints.HINT_SUBTYPE_SET and there are no associated hints.

getParameters

com.sas.entities.AttributeDescriptorInterface[] getParameters()
                                                              throws java.rmi.RemoteException

Deprecated.

Get parameter descriptions. Parameter descriptions from all groups are returned in a single array.

Returns:

an AttributeDescriptorInterface array describing all parameters

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

setParameterValue

void setParameterValue(java.lang.String name,
                       java.lang.Object value)
                       throws java.rmi.RemoteException,
                              com.sas.entities.AttributeSetException

Deprecated.

Sets the value of the specified parameter. The parameter name may be a new name or an existing name. If new, the parameter is added in an implementation defined fashion. If it is desired that the parameter be added to a certain group, an AttributeDescriptorInterface should be created in that group before this method is called. Before any processing is done on the parameter name it is lowercased. See the parameter section on case-sensitivity of the package description documentation for more information.

If the parameter has an Object[] value, what is set on the stored process object (i.e., on the underlying Entity object which implements it) is not the reference passed in but a newly created String object. The toString() method is called on each element of the array and the values are concatenated - separated by the Unit Separator (hex 1f) character - to construct this newly created String object. For stored processes running on a Workspace server only one value is permitted per parameter and if a Object[] is specified it must have only one value. The Unit Separator character used by the Stored Process Service is intended to be transparent to the client. However, clients intending to manipulate the Entity after the call to this method need to be aware of this implementation detail. And, use of this character by the client in the value String can have unintended consequences and is therefore not recommended. How multi-valued parameters are made visible to the SAS stored process code is discussed in the Input Parameters section of the Developer's Guide.

Parameters:

name - name of the parameter. Parameter names have the following restrictions:

• The length of the name must be no greater than 32 characters.
• The first character is either an English letter or an underscore.
• Subsequent characters can be English letters, underscores or digits.

value - value of the parameter value. It is recommended that the value not contain the Unit Separator (hex 1f) character for the reasons described above.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

com.sas.entities.AttributeSetException - - if the type of the value parameter is not appropriate (for reasons as described in the setAttribute() method of the base class) or if an array of more than one element is supplied to a stored process running on the Workspace Server.

java.lang.IllegalStateException - if destroy() has been called.

setParameterValues

void setParameterValues(java.util.Map map)
                        throws java.rmi.RemoteException,
                               com.sas.entities.AttributeSetException

Deprecated.

Sets the values of the specified parameters. For a description of how each parameter is processed see setParameterValue(String, Object).

Parameters:

map - the Map contains parameter name (String) value (Object) pairs.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

com.sas.entities.AttributeSetException - - if the type of the value parameter is not supported.

java.lang.IllegalStateException - if destroy() has been called.

*** This interface provides Binary Compatibility only, not Source Compatibility ***