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

com.sas.services.storedprocess
Interface StoredProcess2Interface

All Superinterfaces:
java.rmi.Remote, StoredProcessBaseInterface

public interface StoredProcess2Interface
extends StoredProcessBaseInterface

This interface describes the second generation of the stored process service object. It extends StoredProcessBaseInterface which contains the methods common to both this interface and StoredProcessInterface. The interface supports stored processes in the Version 1 metadata format introduced in 9.2 as well as stored processes in the Version 2 metadata format introduced in 9.3.

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.

When this service object is constructed, the parameters of the Stored Process are deserialized into a PromptGroupInterface rooted hierarchy and a new PromptValues object is constructed using this PromptGroupInterface. This PromptValuesInterface is available via getPromptValues() and can be used for parameter manipulation. The PromptGroupInterface is available from the PromptValuesInterface. 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.

This parameter model is based on the Prompting Framework and a good understanding of that framework is needed to to fully exploit it.

Since:
9.2

Field Summary
static int RESULT_TYPE_NONE
          No package or stream is delivered by the stored process service.
static int RESULT_TYPE_PACKAGE
          A package is delivered by the stored process service via the ExecutionBaseInterface.getResultPackage() method.
static int RESULT_TYPE_STREAM
          Results are delivered via one of more Streams.
 
Fields inherited from interface com.sas.services.storedprocess.StoredProcessBaseInterface
SERVER_TYPE_STOREDPROCESS, SERVER_TYPE_WORKSPACE
 
Method Summary
 boolean addInputStream(java.lang.String streamKey)
          Adds an input stream definition to the stored process.
 boolean addOutputStream(java.lang.String streamKey, boolean isMultiPass)
          Adds an output stream definition to the stored process.
 Execution2Interface execute(boolean synchronous, ExecutionStatusListener2Interface listener, boolean createAlert, java.lang.Object connection)
          Execute the stored process.
 Execution2Interface executeAsynch(ExecutionStatusListener2Interface listener, boolean createAlert)
          Execute the stored process asynchronously.
 java.lang.String getClientName()
          Returns the client name.
 ConnectionInterface getConnection()
          Get a connection for stored process execution.
 java.util.List<GenericStream> getDataSources()
          Returns a list of the stream data sources.
 java.util.List<GenericStream> getDataTargets()
          Returns a list of stream data targets.
 java.lang.String[] getInputStreamNames()
          Deprecated. Use getDataTargets(). Returns the fileref names of the GenericStream and XMLStream objects returned by getDataTargets().
 OutputParameterInterface getOutputParameter(java.lang.String name)
          Return the OutputParameterInterface object corresponding to the name requested.
 java.util.List<OutputParameterInterface> getOutputParameters()
          Return a list of output parameters defined in metadata as OutputParameterInterface objects.
 java.lang.String[] getOutputStreamNames()
          Deprecated. Use getDataSources(). Returns the fileref names of the GenericStream and XMLStream objects returned by getDataSources().
 com.sas.prompts.definitions.PromptDefinitionInterface[] getParameters()
          Gets parameter descriptions.
 java.lang.Object getParameterValue(java.lang.String parameterName)
          Gets the value of a parameter.
 com.sas.prompts.PromptValuesInterface getPromptValues()
          Returns the PromptValuesInterface associated with this Stored Process service object.
 int getResultType()
          Gets the type of result delivered by the service.
 LogicalServerInterface getServer()
          Get the the logical server the stored process runs on.
 int getServerType()
          Get the type of server that the stored process runs on.
 boolean isPackageCapable()
          Does the stored process have the result capability of package enabled.
 boolean isStreamCapable()
          Does the stored process have the result capability of stream enabled.
 void setClientName(java.lang.String clientName)
          Sets the client name.
 void setInputDataTable(java.lang.String tableName, java.io.InputStream inputStream, java.lang.String memberName, java.lang.String xmlLibraryOptions)
          Specifies client side input to be used for the table via the XML libname engine.
 void setInputDataTable(java.lang.String tableName, java.lang.String libref, java.lang.String memberName)
          Specifies the two level name for a server side input table.
 void setInputFileref(java.lang.String fileref, java.io.InputStream inputStream)
          Associates a client supplied binary file with the fileref.
 void setInputFileref(java.lang.String fileref, java.io.Reader reader)
          Associates a client supplied text file with the fileref.
 void setInputFileref(java.lang.String fileref, java.lang.String engine, java.lang.String path, java.lang.String options)
          Associates a path on the server with the fileref used for input.
 void setLogicalServerType(com.sas.services.storedprocess.metadata.StoredProcessInterface.LogicalServerType logicalServerType)
          Sets the type of logical server to be used for execution.
 void setOutputDataTable(java.lang.String tableName, java.io.OutputStream outputStream, java.lang.String memberName, java.lang.String xmlLibraryOptions)
          Specifies client side output to be used for the table via the XML libname engine.
 void setOutputDataTable(java.lang.String tableName, java.lang.String libref, java.lang.String memberName)
          Specifies the two level name for a server side output table.
 void setOutputFileref(java.lang.String fileref, java.io.OutputStream outputStream)
          Specifies the OutputStream to be used to write the output of the fileref to.
 void setOutputFileref(java.lang.String fileref, java.lang.String engine, java.lang.String path, java.lang.String options)
          Associates a path on the server with the fileref used for output.
 void setOutputFileref(java.lang.String fileref, java.io.Writer writer)
          Specifies the Writer to be used to write the output of the fileref to.
 com.sas.prompts.definitions.PromptDefinitionInterface setParameterValue(java.lang.String name, java.lang.Object value)
          Sets the value of the specified parameter on the PromptValues object associated with this stored process.
 java.util.Map setParameterValues(java.util.Map map)
          Sets the values of the specified parameters.
 java.util.List<com.sas.prompts.definitions.PromptDefinitionInterface> setParameterValues(com.sas.prompts.PromptValuesInterface promptValues)
          Sets values for the parameters of this Stored Process from the PromptValuesInterface supplied.
 void setPromptValues(com.sas.prompts.PromptValuesInterface promptValues)
          Sets the PromptValuesInterface associated with this Stored Process service object.
 void setServerContext(ServerContextInterface serverContext)
          Sets the server context to be used to execute the stored process.
 void validatePromptValues()
          Validates prompt values.
 
Methods inherited from interface com.sas.services.storedprocess.StoredProcessBaseInterface
destroy, getDescription, getDirectory, getFileName, getName, hasParameters, setDescription, setName, setPrivilegedUser, setSourceFromFile
 

Field Detail

RESULT_TYPE_NONE

static final int RESULT_TYPE_NONE
No package or stream is delivered by the stored process service.

See Also:
getResultType(), Constant Field Values

RESULT_TYPE_PACKAGE

static final int RESULT_TYPE_PACKAGE
A package is delivered by the stored process service via the ExecutionBaseInterface.getResultPackage() method.

See Also:
getResultType(), Constant Field Values

RESULT_TYPE_STREAM

static final int RESULT_TYPE_STREAM
Results are delivered via one of more Streams.

See Also:
getResultType(), Constant Field Values
Method Detail

execute

Execution2Interface execute(boolean synchronous,
                            ExecutionStatusListener2Interface listener,
                            boolean createAlert,
                            java.lang.Object connection)
                            throws java.lang.IllegalStateException,
                                   ExecutionException,
                                   java.rmi.RemoteException
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. Another alternative for asynchronous behavior is executeAsynch(ExecutionStatusListener2Interface, boolean).

A discussion of additional input parameters generated by the service can be found here.

Depending on the type of parameter and the associated value, one or more name value pairs may be created to capture the value. Refer to the javadoc of the getMacroVariableValues method of the corresponding type in com.sas.datatypes for details.

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:

After the preliminary processing described above is done, an Execution2Interface is created to capture the state of execution and provide access to results, and then execution proceeds synchronously or asynchronously as requested. The created Execution2Interface 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:

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. Do note a ConnectionInterface is not serializable or remoteable.
  • IWorkspace_1_1: if the stored process executes on a Workspace server. For 9.2 stored processes, the StoredProcess Service obtains the ILanguageService object from the client supplied IWorkspace_1_1. The client should not use the ILanguageService associated with the supplied IWorkspace during the execution of the stored process.
  • IStoredProcessServer_1_1: if the stored process executes on a StoredProcess server.
Returns:
an Execution2Interface object describing the state and the results of the execution. Execution2Interface.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.
  • 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:
  • InvalidPromptValueException - thrown by the Prompting framework while validating prompt values.
  • 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 Execution2Interface.getStatus() and #setLogicalServerType(LogicalServerType).


executeAsynch

Execution2Interface executeAsynch(ExecutionStatusListener2Interface listener,
                                  boolean createAlert)
                                  throws java.lang.IllegalStateException,
                                         ExecutionException,
                                         java.rmi.RemoteException
Execute the stored process asynchronously. 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.

If synchronous behavior is desired see execute(boolean, ExecutionStatusListener2Interface, boolean, Object).

A discussion of additional input parameters generated by the service can be found here.

Depending on the type of parameter and the associated value, one or more name value pairs may be created to capture the value. Refer to the javadoc of the getMacroVariableValues method of the corresponding type in com.sas.datatypes for details.

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:

After the preliminary processing described above is done, an Execution2Interface is created to capture the state of execution and provide access to results and, then, a new thread is created. The created Execution2Interface is returned by this method. In the newly created thread a connection is obtained and stored process execution occurs. Any exceptions that occur in this new thread 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:

Note: the executeAysnch() 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 executeAysnch() invoked again. Or, if there is no further use for the stored process object it may be destroyed.

If this method is used to execute a stored process which streams input and / or output, stream handles via Execution2Interface.getInputStream(Object) or Execution2Interface.getOutputStream(Object) methods will not be available until after a connection to the server is made. If no connection is available, those method will block. The consumer can control blocking behavior by using Execution2Interface.waitForConnection(long) or Execution2Interface.waitForConnection() and not obtaining the streams until a connection has been made.

Parameters:
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.
Returns:
an Execution2Interface object describing the state and the results of the execution. Execution2Interface.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.
  • MissingParameterException - if a parameter that is required has not been assigned a value.
If the super-class ExecutionException is thrown the following could be wrapped:
  • InvalidPromptValueException - thrown by the Prompting framework while validating prompt values.
  • 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 Execution2Interface.getStatus() and #setLogicalServerType(LogicalServerType).


addInputStream

boolean addInputStream(java.lang.String streamKey)
                       throws java.rmi.RemoteException,
                              java.lang.IllegalStateException
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.

If successful, a GenericStream object is added to the list of data targets.

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 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 for version 1 stored processes
  • if destroy() has been called

addOutputStream

boolean addOutputStream(java.lang.String streamKey,
                        boolean isMultiPass)
                        throws java.rmi.RemoteException,
                               java.lang.IllegalStateException
Adds an output stream definition to the stored process. The client writes to the output stream thereby providing input to the stored process.

Input streams and output streams use the same fileref namespace.

If successful, a GenericStream object is added to the list of data sources.

Specified by:
addOutputStream in interface StoredProcessBaseInterface
Parameters:
streamKey - name of the output stream (must be a valid SAS fileref name)
isMultiPass - whether the stream supports multi-pass reads. Required when the stored process needs to make multiple passes over the data.
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 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 input stream
  • if the server type is not StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS for version 1 stored processes
  • if destroy() has been called

isStreamCapable

boolean isStreamCapable()
                        throws java.rmi.RemoteException
Does the stored process have the result capability of stream enabled.

Returns:
true if the stored process is capable of streaming output; false, if not capable
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.

isPackageCapable

boolean isPackageCapable()
                         throws java.rmi.RemoteException
Does the stored process have the result capability of package enabled.

Returns:
true if the stored process is capable of package output; false, if not capable
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.

getParameters

com.sas.prompts.definitions.PromptDefinitionInterface[] getParameters()
                                                                      throws java.rmi.RemoteException
Gets parameter descriptions. Parameter descriptions from all groups are returned in a single array.

Returns:
a PromptDefinitionInterface array describing all parameters. Note: PromptDefinitionInterface is not remoteable
Throws:
java.lang.IllegalStateException - if destroy() has been called.
java.rmi.RemoteException - if a network anomaly is encountered.

getParameterValue

java.lang.Object getParameterValue(java.lang.String parameterName)
                                   throws java.rmi.RemoteException
Gets the value of a parameter. The parameter name supplied is compared with the prompt names in a case-insensitive way. For a properly defined stored process there should be at most one parameter with the same name which has a value. If there are multiple parameters with the same name which have values, the first one in visual order is returned. A null is returned if there is no value assigned to the parameter.

Returns:
the value of the parameter; null, if there's none
Throws:
java.lang.IllegalStateException - if destroy() has been called.
java.rmi.RemoteException - if a network anomaly is encountered.

setParameterValue

com.sas.prompts.definitions.PromptDefinitionInterface setParameterValue(java.lang.String name,
                                                                        java.lang.Object value)
                                                                        throws java.rmi.RemoteException,
                                                                               ServiceException,
                                                                               com.sas.prompts.InvalidPromptValueException
Sets the value of the specified parameter on the PromptValues object associated with this stored process. The parameter name may be a new name or an existing name. See the parameter section on case-sensitivity of the package description documentation for more information on case-sensitivity issues of parameter names.

If new, the parameter is added in an implementation defined fashion and the only allowed values are of type String or String[] - supplying a value of any other type or a null value will result in a ServiceException.

If it is desired that the parameter be added to a certain group or values of a type other than String or String[] be handled, a PromptDefinitionInterface should be appropriately created before this method is called.

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.
Returns:
the PromptDefinitionInterface corresponding to the parameter. Note: PromptDefinitionInterface is not remoteable
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
com.sas.prompts.InvalidPromptValueException - if thrown by the underlying Prompting Framework
ServiceException - if the parameter name is not valid or if the value is not of type String or String[] for a new parameter
java.lang.IllegalStateException - if destroy() has been called.

setParameterValues

java.util.Map setParameterValues(java.util.Map map)
                                 throws java.rmi.RemoteException,
                                        ServiceException
Sets the values of the specified parameters. The map keys are new or existing parameter names. See the section on parameter name case-sensitivity in the package description documentation for more information on case-sensitivity issues of parameter names.

The name is first validated. Next, the actual setting of values is delegated to the setPromptValuesByNameValuePair method of PromptUtil. That method ignores any prompt definition with a prompt name which does not exists in this Stored Process. Finally, new parameters (those ignored by the PromptUtil method) are added using setParameterValue(String, Object).

Parameters:
map - the Map containing values - the key is a String representing the parameter name and the value is the Object representing the parameter value
Returns:
a Map of errors that occurred. The key is the prompt name and the value is the exception which occurred processing the prompt with that name.
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
ServiceException - if there is an error in name validation
java.lang.IllegalArgumentException - if any of the Map keys are not Strings.
java.lang.IllegalStateException - if destroy() has been called.

getPromptValues

com.sas.prompts.PromptValuesInterface getPromptValues()
                                                      throws java.rmi.RemoteException
Returns the PromptValuesInterface associated with this Stored Process service object. When a stored process is instantiated from metadata, prompts are deserialized into a PromptGroup object. If the stored process has no parameters the deserialization process results in an empty PromptGroup object. A PromptValues object is constructed from the PromptGroup object and a reference to that PromptValues object is returned by this method.

Returns:
the PromptValuesInterface. Note: PromptValuesInterface is not remoteable
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
java.lang.IllegalStateException - if destroy() has been called.

setPromptValues

void setPromptValues(com.sas.prompts.PromptValuesInterface promptValues)
                     throws java.rmi.RemoteException
Sets the PromptValuesInterface associated with this Stored Process service object. When a stored process is instantiated from metadata, prompts are deserialized into a PromptGroup object and a PromptValues object is constructed from the PromptGroup object. This PromptValues is used to maintain values associated with stored process parameters. Calling this method replaces the PromptValues object used by stored process with the supplied parameter. The old PromptValues is discarded and the new one used - no merge of any kind is done.

Parameters:
promptValues - PromptValuesInterface that is to replace the PromptValuesInterface used by this Stored Process
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
java.lang.IllegalStateException - if destroy() has been called.

setParameterValues

java.util.List<com.sas.prompts.definitions.PromptDefinitionInterface> setParameterValues(com.sas.prompts.PromptValuesInterface promptValues)
                                                                                         throws java.rmi.RemoteException,
                                                                                                ServiceException
Sets values for the parameters of this Stored Process from the PromptValuesInterface supplied. The intent is for the actual setting of values to be delegated to the setPromptValuesByNameValuePair method of PromptUtil. That method ignores any prompt definition with a prompt name which does not exists in this Stored Process - such PromptDefinitions are added to a list which is returned. If there are no values in this category an empty list is returned. If a PromptDefinition has its value cleared in the input PromptValuesInterface an existing prompt of the same name in the Stored Process is cleared except if it has default value different from that in the Stored Process in which case the incoming default value will be used.

Fixed prompts are not affected by this method.

If the PromptValuesInterface supplied is the same (identical reference) as the one used by the stored process (which is the one surfaced via getPromptValues()), this method is a no-op and returns an empty list.

If an Exception occurs in setting the value, the exception is captured and a Info level message containing the exception written to the log.

The intent of this method is for the stored process to be supplied with parameter values for execution. If prompt manipulation or maintenance of UI state is desired consumers should consider obtaining the prompts via getPromptValues(), doing needed manipulation and then setting them on the stored process via setPromptValues(PromptValuesInterface).

Parameters:
promptValues - PromptValuesInterface containing parameter values that are to be set on this Stored Process
Returns:
the list of PromptDefinitionInterfaces as described above. Note: PromptDefinitionInterface is not remoteable
Throws:
java.rmi.RemoteException
ServiceException

getOutputParameters

java.util.List<OutputParameterInterface> getOutputParameters()
                                                             throws java.rmi.RemoteException
Return a list of output parameters defined in metadata as OutputParameterInterface objects.

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

getOutputParameter

OutputParameterInterface getOutputParameter(java.lang.String name)
                                            throws java.rmi.RemoteException
Return the OutputParameterInterface object corresponding to the name requested. OutputParameterInterface objects are only available in this interface for output parameters defined in metadata.

Parameters:
name - of the output parameter requested
Returns:
null if a matching object cannot be found.
Throws:
java.rmi.RemoteException - if a network anomaly is encountered

getInputStreamNames

java.lang.String[] getInputStreamNames()
                                       throws java.rmi.RemoteException,
                                              java.lang.IllegalStateException
Deprecated. Use getDataTargets(). Returns the fileref names of the GenericStream and XMLStream objects returned by getDataTargets().

Description copied from interface: StoredProcessBaseInterface
Return an array of input stream names for this stored process.

Specified by:
getInputStreamNames in interface StoredProcessBaseInterface
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
java.lang.IllegalStateException - if the stored process runs on a WorkspaceServer or if destroy() has been called.

getOutputStreamNames

java.lang.String[] getOutputStreamNames()
                                        throws java.rmi.RemoteException,
                                               java.lang.IllegalStateException
Deprecated. Use getDataSources(). Returns the fileref names of the GenericStream and XMLStream objects returned by getDataSources().

Description copied from interface: StoredProcessBaseInterface
Return an array of output stream names for this stored process.

Specified by:
getOutputStreamNames in interface StoredProcessBaseInterface
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
java.lang.IllegalStateException - if the stored process runs on a WorkspaceServer or if destroy() has been called.

getDataSources

java.util.List<GenericStream> getDataSources()
                                             throws java.rmi.RemoteException
Returns a list of the stream data sources. Each object in the list is one of: The items are returned in the order defined at design time.

This method returns the types of data sources that can be present in a 9.2 stored process and does not return the types of data sources introduced post 9.2.

Returns:
the list of data sources
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
java.lang.IllegalStateException - if destroy() has been called.

getDataTargets

java.util.List<GenericStream> getDataTargets()
                                             throws java.rmi.RemoteException
Returns a list of stream data targets. Each object in the list is one of: The items are returned in the order defined at design time.

This method returns the types of data sources that can be present in a 9.2 stored process and does not return the types of data sources introduced post 9.2.

Returns:
the list of data targets
Throws:
java.rmi.RemoteException - if a network anomaly is encountered.
java.lang.IllegalStateException - if destroy() has been called.

setClientName

void setClientName(java.lang.String clientName)
                   throws java.rmi.RemoteException
Sets the client name. Calling this method will overwrite the client name that a stored process obtains from the service (via StoredProcessServiceInterface.getClientName()) at construction time.

Parameters:
clientName - client name
Throws:
java.rmi.RemoteException

getClientName

java.lang.String getClientName()
                               throws java.rmi.RemoteException
Returns the client name. See setClientName(String) for more information.

Returns:
the client name
Throws:
java.rmi.RemoteException

getResultType

int getResultType()
                  throws ServiceException,
                         java.rmi.RemoteException
Gets the type of result delivered by the service.

Returns:
one of RESULT_TYPE_NONE, RESULT_TYPE_PACKAGE or RESULT_TYPE_STREAM
Throws:
java.lang.IllegalStateException - if destroy() has been called.
java.rmi.RemoteException - if a network anomaly is encountered.
ServiceException - if there are inconsistencies among the capabilities of the stored process, the parameter values and the type of server the stored process is running on

validatePromptValues

void validatePromptValues()
                          throws java.lang.IllegalStateException,
                                 com.sas.prompts.InvalidPromptValueException,
                                 java.rmi.RemoteException
Validates prompt values. The following is done:

If there is a validation error the exception message contains the reason.

Throws:
com.sas.prompts.InvalidPromptValueException - if there is a validation error
java.lang.IllegalStateException - if the object bound to the SessionContext using "com.sas.prompts.dataProviderKey" is not an instance of DataProviderInterface
java.rmi.RemoteException - if a network anomaly is encountered.

setInputFileref

void setInputFileref(java.lang.String fileref,
                     java.io.InputStream inputStream)
                     throws ServiceException,
                            java.rmi.RemoteException
Associates a client supplied binary file with the fileref. The consumer of the API supplies the InputStream that the service will read from. Before the stored process executes, bytes from the InputStream will be copied to a temporary file on the server and the service will associate that temporary file with the fileref. The service closes the supplied InputStream when it has completed reading from it.

If this method is invoked on a remote object, a serializable extension of InputStream, e.g., InputStreamAdapter should be supplied.

Parameters:
fileref -
inputStream -
Throws:
ServiceException - if the fileref is not defined or the fileref is used for output
java.rmi.RemoteException
Since:
9.3

setInputFileref

void setInputFileref(java.lang.String fileref,
                     java.io.Reader reader)
                     throws ServiceException,
                            java.rmi.RemoteException
Associates a client supplied text file with the fileref. The consumer of the API supplies the Reader that the service will read from. Before the stored process executes, characters from the Reader will be copied to a temporary file on the server and the service will associate that temporary file with the fileref. The service closes the supplied Reader when it has completed reading from it.

If this method is invoked on a remote object, a serializable extension of Reader, e.g., ReaderAdapter should be supplied.

Parameters:
fileref -
inputStream -
Throws:
ServiceException - if the fileref is not defined or the fileref is used for output
java.rmi.RemoteException
Since:
9.3

setInputFileref

void setInputFileref(java.lang.String fileref,
                     java.lang.String engine,
                     java.lang.String path,
                     java.lang.String options)
                     throws ServiceException,
                            java.rmi.RemoteException
Associates a path on the server with the fileref used for input. The consumer of the API may optionally specify the engine to be used to access the path and any options needed by the engine. Before the stored process executes, the path will be associated with the fileref using any engine specified.

Parameters:
fileref -
inputStream -
Throws:
ServiceException - if the fileref is not defined or the fileref is used for output
java.rmi.RemoteException
Since:
9.3

setOutputFileref

void setOutputFileref(java.lang.String fileref,
                      java.io.OutputStream outputStream)
                      throws ServiceException,
                             java.rmi.RemoteException
Specifies the OutputStream to be used to write the output of the fileref to. The consumer of the API supplies the OutputStream that the service will write to. Before the stored process executes, a temporary file on the server is associated with the fileref and after execution completes bytes from that temporary file are written to the supplied OutputStream. The service closes the supplied OutputStream when it has completed writing to it.

If this method is invoked on a remote object, a serializable extension of OutputStream, e.g., OutputStreamProxy should be supplied.

Parameters:
fileref -
inputStream -
Throws:
ServiceException - if the fileref is not defined or the fileref is used for input
java.rmi.RemoteException
Since:
9.3

setOutputFileref

void setOutputFileref(java.lang.String fileref,
                      java.io.Writer writer)
                      throws ServiceException,
                             java.rmi.RemoteException
Specifies the Writer to be used to write the output of the fileref to. The consumer of the API supplies the Writer that the service will write to. Before the stored process executes, a temporary file on the server is associated with the fileref and after execution completes characters from that temporary file are written to the supplied Writer. The service closes the supplied Writer when it has completed writing to it.

If this method is invoked on a remote object, a serializable extension of Writer, e.g., WriterProxy should be supplied.

Parameters:
fileref -
inputStream -
Throws:
ServiceException - if the fileref is not defined or the fileref is used for input
java.rmi.RemoteException
Since:
9.3

setOutputFileref

void setOutputFileref(java.lang.String fileref,
                      java.lang.String engine,
                      java.lang.String path,
                      java.lang.String options)
                      throws ServiceException,
                             java.rmi.RemoteException
Associates a path on the server with the fileref used for output. The consumer of the API may optionally specify the engine to be used to access the path and any options needed by the engine. Before the stored process executes, the path will be associated with the fileref using any engine specified.

Parameters:
fileref -
inputStream -
Throws:
ServiceException - if the fileref is not defined or the fileref is used for input
java.rmi.RemoteException
Since:
9.3

setInputDataTable

void setInputDataTable(java.lang.String tableName,
                       java.lang.String libref,
                       java.lang.String memberName)
                       throws ServiceException,
                              java.rmi.RemoteException
Specifies the two level name for a server side input table. It is assumed that the libref has been defined outside of the stored process (e.g. preassigned). The service adds a macro name-value pair using as follows: the name is the value of the tableName parameter prefixed by "_SOURCE_" and the value is the value derived from the values of the libref and memberName parameters as in libref.memberName.

If null or an empty string is specified for libref a one level name results.

If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

Parameters:
tableName - the table parameter name of a data table in metadata
libref - name of the libref
memberName - name of the dataset in the libref
Throws:
ServiceException
java.rmi.RemoteException
Since:
9.3

setInputDataTable

void setInputDataTable(java.lang.String tableName,
                       java.io.InputStream inputStream,
                       java.lang.String memberName,
                       java.lang.String xmlLibraryOptions)
                       throws ServiceException,
                              java.rmi.RemoteException
Specifies client side input to be used for the table via the XML libname engine. This method results in the service issuing a LIBNAME statement and a FILENAME statement using a generated name of the form _STPnnnn (n is an upper case hex-digit). The LIBNAME statement specifies the XML engine with any options specified in the xmlLibraryOptions parameter. The FILENAME specifies a TEMP device and input are (binary) copied from the InputStream to the location of the fileref before the stored process executes. The service adds a macro name-value pair using the generated name and the input provided. The name is the value of the tableName parameter prefixed by "_SOURCE_" and the value is the value derived from the values of the generated name and the memberName parameter as in _STPnnnn.member.

If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

Parameters:
tableName - the table parameter name of a data table in metadata
inputStream - which provides the (binary) input to the stored process
memberName - name of the dataset in the libref
xmlLibraryOptions - options to be used when the LIBNAME statement using the XML libname engine is issued
Throws:
ServiceException
java.rmi.RemoteException
Since:
9.3

setOutputDataTable

void setOutputDataTable(java.lang.String tableName,
                        java.lang.String libref,
                        java.lang.String memberName)
                        throws ServiceException,
                               java.rmi.RemoteException
Specifies the two level name for a server side output table. It is assumed that the libref has been defined outside of the stored process (e.g. preassigned). The service adds a macro name-value pair using as follows: the name is the value of the tableName parameter prefixed by "_TARGET_" and the value is the value derived from the values of the libref and memberName parameters as in libref.memberName.

If null or an empty string is specified for libref a one level name results.

If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

Parameters:
tableName - the table parameter name of a data table in metadata
libref - name of the libref
memberName - name of the dataset in the libref
Throws:
ServiceException
java.rmi.RemoteException
Since:
9.3

setOutputDataTable

void setOutputDataTable(java.lang.String tableName,
                        java.io.OutputStream outputStream,
                        java.lang.String memberName,
                        java.lang.String xmlLibraryOptions)
                        throws ServiceException,
                               java.rmi.RemoteException
Specifies client side output to be used for the table via the XML libname engine. This method results in the service issuing a LIBNAME statement and a FILENAME statement using a generated name of the form _STPnnnn (n is an upper case hex-digit). The LIBNAME statement specifies the XML engine with any options specified in the xmlLibraryOptions parameter. The FILENAME specifies a TEMP device and output is (binary) copied to the OutputStream from the location of the fileref after the stored process executes. The service adds a macro name-value pair using the generated name and the input provided. The name is the value of the tableName parameter prefixed by "_TARGET_" and the value is the value derived from the values of the generated name and the memberName parameter as in _STPnnnn.member.

If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

Parameters:
tableName - the table parameter name of a data table in metadata
outputStream - which provides the output from the stored process
memberName - name of the dataset in the libref
xmlLibraryOptions - options to be used when the LIBNAME statement using the XML libname engine is issued
Throws:
ServiceException
java.rmi.RemoteException
Since:
9.3

setServerContext

void setServerContext(ServerContextInterface serverContext)
                      throws ServiceException,
                             java.rmi.RemoteException
Sets the server context to be used to execute the stored process. This method may only be called for stored processes created from metadata if the stored process is defined to permit execution on other server contexts. For such stored processes, StoredProcessInterface.isOtherServerContextAllowed() returns true.

For stored process defined with a logical server type of StoredProcessInterface.LogicalServerType.WORKSPACE or StoredProcessInterface.LogicalServerType.STORED_PROCESS, this method checks to see if a server of that type exists and will throw a ServiceException if it does not.

For stored process defined with a logical server type of StoredProcessInterface.LogicalServerType.ANY this method checks to see if a server of either supported type exists and will throw a ServiceException if one cannot be found.

If both this method and #setLogicalServerType(LogicalServerType) are to be called, this method should be called first and then setLogicalServerType() should be called as setLogicalServerType() checks metadata to ensure that a server of the desired type is defined. If this method is called after setLogicalServerType() the value set by setLogicalServerType() will be ignored as this method uses the value defined in metadata. Calls to getServer() and getServerType() should not be made until calls to both this method and setLogicalServerType() are complete. This method is invalid for 9.2 stored processes or manually created stored processes and will throw an UnsupportedOperationException if invoked on one.

Parameters:
serverContext - to be used for execution
Throws:
ServiceException - if the stored process does not permit execution on other server contexts, if there is a metadata error, or for the reasons described above
java.rmi.RemoteException
Since:
9.3

setLogicalServerType

void setLogicalServerType(com.sas.services.storedprocess.metadata.StoredProcessInterface.LogicalServerType logicalServerType)
                          throws ServiceException,
                                 java.rmi.RemoteException
Sets the type of logical server to be used for execution. This method may only be called for stored processes created from metadata if the stored process is defined to permit execution on any type of logical server. For such stored processes, StoredProcessInterface.getLogicalServerType() returns StoredProcessInterface.LogicalServerType.ANY.

If a stored process is defined with StoredProcessInterface.LogicalServerType.ANY, an attempt is made to first get a connection to a Stored Process server. If the attempt is successful that connection is used; if unsuccessful, an attempt is next made to obtain a connection to a Workspace server. Invoking this method restricts the connection attempt to the type of server specified; if no connection can be made to the specified type of server, no additional attempt is made to connect to a different type of server.

The only valid arguments are StoredProcessInterface.LogicalServerType.STORED_PROCESS and StoredProcessInterface.LogicalServerType.WORKSPACE.

If both this method and setServerContext() are to be called, setServerContext() should be called first and then this method should be called. See setServerContext(ServerContextInterface) for more information.

This method checks metadata to ensure that a server of the desired type is defined for the server context in effect.

This method is invalid for 9.2 stored processes or manually created stored processes and will throw an UnsupportedOperationException if invoked on one.

Parameters:
logicalServerType - the type of server to connect to
Throws:
ServiceException - if the stored process does not permit execution on any logical server type, if the argument is not valid, if a server of the type desired is not defined in metadata or if there is a metadata exception
java.rmi.RemoteException
Since:
9.3

getServer

LogicalServerInterface getServer()
                                 throws java.rmi.RemoteException
Get the the logical server the stored process runs on.

For 9.2 stored processes this method returns the LogicalServer associated with the stored process.

For other stored processes, the LogicalServer returned depends on the Logical Servers attached to the Server Context and the logical server type defined in metadata and any prior calls to #setLogicalServerType(LogicalServerType) and setServerContext(ServerContextInterface). See setServerContext(ServerContextInterface) for additional information. The LogicalServer returned is based on metadata and the various settings previously described and not on whether the server is actually running.

Specified by:
getServer in interface StoredProcessBaseInterface
Throws:
java.lang.IllegalStateException - if destroy() has been called.
java.rmi.RemoteException - if a network anomaly is encountered.

getServerType

int getServerType()
                  throws java.rmi.RemoteException
Get the type of server that the stored process runs on.

For other stored processes, the type returned depends on the Logical Servers attached to the Server Context and the logical server type defined in metadata and any prior calls to #setLogicalServerType(LogicalServerType) and setServerContext(ServerContextInterface). See setServerContext(ServerContextInterface) for additional information. The type returned is based on metadata and the various settings previously described and not on whether the server is actually running.

Specified by:
getServerType in interface StoredProcessBaseInterface
Returns:
StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS or StoredProcessBaseInterface.SERVER_TYPE_WORKSPACE
Throws:
java.lang.IllegalStateException - if destroy() has been called.
java.rmi.RemoteException - if a network anomaly is encountered.

getConnection

ConnectionInterface getConnection()
                                  throws ServiceException,
                                         java.rmi.RemoteException
Get a connection for stored process execution. This method is called if the consumer needs to use the connection that the stored process will use for purposes other than and including the execution of the stored process. The connection returned by this method can be used by the consumer before and / or after the execution of the stored process. Typically, it is also used in the call to execute the stored process, by supplying it as the last parameter to execute(boolean, ExecutionStatusListener2Interface, boolean, Object).

If the consumer calls this method, the consumer is responsible for managing the life-cycle of the connection. The returned connection can be closed using ConnectionInterface.close() and the returned connection should be closed after Execution2Interface.destroy() has been called.

If the stored process supports it, the method will honor any prior call to setServerContext(ServerContextInterface) and #setLogicalServerType(LogicalServerType). The method uses the same algorithm to obtain a connection as used by the stored process service when the execute method is called without a supplied connection.

Do note that ConnectionInterface, the type returned by this method, is not serializable or remoteable.

Returns:
connection which can be used to execute the stored process
Throws:
ServiceException - if a connection could not be obtained
java.lang.UnsupportedOperationException - if the method is called on a manually created stored process
java.rmi.RemoteException

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




Copyright © 2009 SAS Institute Inc. All Rights Reserved.