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

com.sas.services.publish
Interface ResultPackageInterface

All Superinterfaces:

com.sas.entities.EntityKeyInterface, EntryInterface, com.sas.io.InputStreamProviderInterface, java.rmi.Remote

All Known Implementing Classes:

ResultPackage

public interface ResultPackageInterface
extends EntryInterface, com.sas.io.InputStreamProviderInterface, java.rmi.Remote

The ResultPackageInterface provides a mechanism for setting and getting the attributes of a result package. A result package is a collection of information, such as a collection of reports, tables and documents. A package can contain text files, binary files (such as GIF or JPG), HTML files, references, viewer files and SAS files such as SAS datasets. The ResultPackageInterface provides access to all the result package attributes and to all the entries included in the package.

Package metadata can be defined to provide more information about the result package:

• Abstract - An abstract can be assigned to the result package. Analogous to the abstract of a technical paper, the result package abstract is typically a paragraph length overview of the contents of the package. It is assigned by the package's creator.
• Creation Date/Time - The creation datetime stamp indicates the result package creation date and time. The creation datetime is assigned when the result package is published. The value is in UTC (not local) time.
• Description - This description is typically a single line summary of the package contents. It is assigned by the package's creator.
• Expiration Date/Time - The expiration datetime indicates the date and time on which the result package is scheduled to expire. The expiration datetime is assigned by the packages's creator. If not specified, the value of Dec 31, 9999 will be assigned when the result package is published. The publish framework does not enforce the expiration. It is up to the calling application to use this expiration value as desired. The value should be stored and interpreted in UTC (not local) time.
• Name/Values - The result package name/values can be assigned to the result package to provide user or application control information that describes the package. Name/value pairs are typically assigned to support subsequent package retrieval in search operations, but they could be used for other purposes as well.

Since:

1.0

See Also:

TransportFactory

Method Summary

void	addEntry(EntryInterface entry) Adds a new entry to the result package.
void	close() Close the result package.
void	delete() Delete the result package.
java.lang.String	getAbstract() Returns the abstract of the result package.
long	getCreationDateTime() Returns the creation datetime stamp.
EntryInterface[]	getEntries() Return an array of all entries in this package.
EntryInterface	getEntry(int index) Returns a particular result package entry as indicated by the specified index.
EntryInterface	getEntry(java.lang.String uniqueId) Returns the result package entry identified by the entity key.
EventDataInterface	getEventData() Returns the event data.
long	getExpirationDateTime() Returns the expiration datetime stamp.
java.io.InputStream	getInputStream() Gets the input stream for this result package.
java.io.InputStream	getInputStream(java.lang.Object streamID) Deprecated. Use getInputStream() which now supports remote input streams.
java.lang.String	getName() Returns the name for this result package.
com.sas.io.RemoteInputStreamInterface	getRemoteInputStream(java.lang.Object streamID) Deprecated. Use getInputStream() which now supports remote input streams.
java.lang.Object	hasInputStream() Deprecated. this method no longer needed as getInputStream() will return an input stream that can be used in a remote environment
boolean	isNested() Returns true when the result package is a nested package.
void	setAbstract(java.lang.String description) Set the abstract for the result package.
void	setExpirationDateTime(long expiration) Sets the expiration datetime stamp for the result package.
void	setName(java.lang.String name) Set the name for the result package.

Methods inherited from interface com.sas.services.publish.EntryInterface

getDescription, getNameValuePairs, getURL, isReadOnly, setDescription, setNameValuePairs

Method Detail

getAbstract

java.lang.String getAbstract()
                             throws java.lang.IllegalStateException,
                                    TransportException,
                                    java.rmi.RemoteException

Returns the abstract of the result package.

Returns:

String The abstract of the result package; can be null.

Throws:

java.lang.IllegalStateException - If the result package has already been closed.

TransportException - If the transport encounters an error getting the abstract.

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

setAbstract

void setAbstract(java.lang.String description)
                 throws java.lang.IllegalStateException,
                        java.rmi.RemoteException

Set the abstract for the result package.

Parameters:

description - Plain text that is the abstract for this result package.

Throws:

java.lang.IllegalStateException - If the result package is read only or the result package has already been closed.

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

getExpirationDateTime

long getExpirationDateTime()
                           throws java.lang.IllegalStateException,
                                  TransportException,
                                  java.rmi.RemoteException

Returns the expiration datetime stamp. The publish framework does not enforce the expiration. It is up to the calling application to use this expiration value as desired. The value should be stored and interpreted in UTC (not local) time.

Returns:

long The expiration datetime stamp for this result package.

Throws:

java.lang.IllegalStateException - If the result package has already been closed.

TransportException - If the transport encounters an error getting the expiration datetime stamp.

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

setExpirationDateTime

void setExpirationDateTime(long expiration)
                           throws java.lang.IllegalStateException,
                                  java.rmi.RemoteException

Sets the expiration datetime stamp for the result package. The expiration datetime indicates the date and time on which the result package is scheduled to expire. The publish framework does not enforce the expiration. It is up to the calling application to use this expiration value as desired. The value should be stored and interpreted in UTC (not local) time.

Parameters:

expiration - The expiration datetime stamp for this result package.

Throws:

java.lang.IllegalStateException - If the result package is read only or the result package has already been closed.

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

getCreationDateTime

long getCreationDateTime()
                         throws java.lang.IllegalStateException,
                                TransportException,
                                java.rmi.RemoteException

Returns the creation datetime stamp. The creation datetime stamp indicates the result package creation date and time. The creation datetime is assigned when the result package is published. The value is in UTC (not local) time.

Returns:

long The creation datetime stamp for this result package.

Throws:

java.lang.IllegalStateException - If the result package is an existing package that is being retrieved or if the result package has already been closed.

TransportException - If the transport encounters an error getting the creation datetime stamp.

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

getName

java.lang.String getName()
                         throws java.lang.IllegalStateException,
                                TransportException,
                                java.rmi.RemoteException

Returns the name for this result package. The package name will differe based on the delivery transport that was used to retrieve the result package.

If the result package is retrieved using the archive transport, the name will be the canonical name of the .spk file. If the result package is a nested package, only the name of the nested .spk file is returned (not the complete path).

If the result package is retrieved using the WebDAV transport, the name will be the complete URL of the result package. If the result package is a nested package, only the name of of the nested package is returned (not the complete URL).

If the result package is retrieved using the requester transport, the name will be null.

Returns:

String The name of the result package; can be null.

Throws:

java.lang.IllegalStateException - If the result package has already been closed.

TransportException - If the transport encounters an error getting the nested name.

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

setName

void setName(java.lang.String name)
             throws java.lang.IllegalStateException,
                    java.rmi.RemoteException

Set the name for the result package. This name will only be used if the result package is published as a nested package. A result package can be nested by adding it as an entry to another result package. When the nested package is published, a unique nested package name is generated by the transports. This can be overridden by providing the nested name to use.

Parameters:

name - The name for this result package if published as a nested package; can be null.

Throws:

java.lang.IllegalStateException - If the result package is read only or the result package has already been closed.

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

getEntry

EntryInterface getEntry(int index)
                        throws java.lang.IllegalStateException,
                               java.rmi.RemoteException,
                               TransportException

Returns a particular result package entry as indicated by the specified index. Distributed applications should use {#link getEntries} to obtain the array of entries. It is more efficient to obtain the entire entry array in one request, instead of invoking this method to obtain each entry separately.

Parameters:

index - The zero-based index of the desired result package entry.

Returns:

EntryInterface The result package entry.

Throws:

java.lang.IllegalStateException - If the result package has already been closed.

TransportException - If the transport encounters an error getting the entry.

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

getEntry

EntryInterface getEntry(java.lang.String uniqueId)
                        throws java.lang.IllegalStateException,
                               java.rmi.RemoteException,
                               TransportException

Returns the result package entry identified by the entity key.

Parameters:

uniqueId - The unique identifier of the desired result package entry.

Returns:

EntryInterface The result package entry. This may be null if no entry is found with the specified identifier.

Throws:

java.lang.IllegalStateException - If the result package has already been closed.

TransportException - If the transport encounters an error getting the entry.

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

getEntries

EntryInterface[] getEntries()
                            throws java.lang.IllegalStateException,
                                   java.rmi.RemoteException,
                                   TransportException

Return an array of all entries in this package. Distributed applications should use this method to obtain the package entries because it is more efficient to get all the entries in one request.

Returns:

EntryInterface [] An array of EntryInterface objects.

Throws:

java.lang.IllegalStateException - If the result package has already been closed.

TransportException - If the transport encounters an error getting the entry.

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

addEntry

void addEntry(EntryInterface entry)
              throws java.lang.IllegalStateException,
                     java.rmi.RemoteException

Adds a new entry to the result package. The entry will be added to the end of the entry array. This method will fail if the result package is browse only.

Parameters:

entry - The entry to add to the result package.

Throws:

java.lang.IllegalStateException - If the result package is read only or the result package has already been closed.

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

isNested

boolean isNested()
                 throws java.rmi.RemoteException,
                        java.lang.IllegalStateException

Returns true when the result package is a nested package. A result package can be nested by adding it as an entry to another result package.

Returns:

boolean True if the result package is a nested package; otherwise if this is the main package, false is returned.

Throws:

java.lang.IllegalStateException - If the result package is a new package under construction or if the result package has already been closed. A package under construction can be inserted as an entry into another package, and thus the nested context cannot be determined.

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

close

void close()
           throws java.lang.IllegalStateException,
                  TransportException,
                  java.rmi.RemoteException

Close the result package. All resources associated with the result package will be freed. Once closed, the result package and its entries will throw an IllegalStateException if they are accessed.

Throws:

java.lang.IllegalStateException - If the result package has already been closed or if this is a nested package.

TransportException - If the transport encounters an error getting the entry.

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

delete

void delete()
            throws java.lang.UnsupportedOperationException,
                   TransportException,
                   java.rmi.RemoteException

Delete the result package. This method cannot be invoked on a nested package. The delete method will close and delete the result package.

Throws:

java.lang.UnsupportedOperationException - If the operation is not supported by the transport.

java.lang.IllegalStateException - If the result package is being constructed, if this is a nested package, or if the result package has already been closed.

TransportException - If the transport encounters an error deleting the package.

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

getEventData

EventDataInterface getEventData()
                                throws TransportException,
                                       java.rmi.RemoteException

Returns the event data. This includes the SASPackage XML event body that describes this result package, as well as the event persistence information. See SASPackage Event Usage for more details.

Returns:

EventDataInterface The event data which includes the SASPackage event body, and the event persistence information.

Throws:

TransportException - If the transport encounters an error getting the nested name.

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

getInputStream

java.io.InputStream getInputStream(java.lang.Object streamID)
                                   throws java.rmi.UnmarshalException,
                                          java.io.IOException,
                                          java.rmi.RemoteException,
                                          java.lang.IllegalStateException

Deprecated. Use getInputStream() which now supports remote input streams.

Gets the input stream for this result package. Because input streams are not remotable, this method will throw a RemoteException if it is invoked on a remote object. Distributed applications should utilize getRemoteInputStream(java.lang.Object) in order to obtain the input stream. Only the Requester transport provides the ability to obtain an input stream.

Specified by:

getInputStream in interface com.sas.io.InputStreamProviderInterface

Parameters:

streamID - The stream description should be null; it will be ignored.

Returns:

The input stream that can be used for reading the contents of the result package; null if the transport does not support it or if the method is invoked on a nested package.

Throws:

java.rmi.UnmarshalException - If invoked on a remote object.

java.io.IOException - If an error occurs constructing the input stream.

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

java.lang.IllegalStateException - If the package containing this entry is already closed.

getRemoteInputStream

com.sas.io.RemoteInputStreamInterface getRemoteInputStream(java.lang.Object streamID)
                                                           throws java.io.IOException,
                                                                  java.rmi.RemoteException,
                                                                  java.lang.IllegalStateException

Deprecated. Use getInputStream() which now supports remote input streams.

Get the remote input stream for this result package. Because input streams are not remotable, distributed applications should use remote input streams. Only the Requester transport provides the ability to obtain an input stream.

Specified by:

getRemoteInputStream in interface com.sas.io.InputStreamProviderInterface

Parameters:

streamID - The stream description should be null; it will be ignored.

Returns:

RemoteInputStream The remote input stream that can be used for reading the contents of the result package; null if the method is invoked on a nested package.

Throws:

java.io.IOException - If an error occurs constructing the remote input stream.

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

java.lang.IllegalStateException - If the package containing this entry is already closed.

getInputStream

java.io.InputStream getInputStream()
                                   throws java.io.IOException,
                                          java.rmi.RemoteException,
                                          java.lang.IllegalStateException

Gets the input stream for this result package.

Returns:

The input stream that can be used for reading the contents of the result package; null if the transport does not support it or if the method is invoked on a nested package.

Throws:

java.io.IOException - If an error occurs constructing the input stream.

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

java.lang.IllegalStateException - If the package containing this entry is already closed.

hasInputStream

java.lang.Object hasInputStream()
                                throws java.rmi.UnmarshalException,
                                       java.rmi.RemoteException

Deprecated. this method no longer needed as getInputStream() will return an input stream that can be used in a remote environment

Check if getInputStream(java.lang.Object) will succeed. See getInputStream(java.lang.Object) to determine whether this method should be used.

Specified by:

hasInputStream in interface com.sas.io.InputStreamProviderInterface

Returns:

Object non-null if getInputStream(java.lang.Object) would succeed; throws UnmarshalException if it would fail

Throws:

java.rmi.UnmarshalException - if invoked on a remote obejct

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

java.lang.IllegalStateException - if this result package has already been closed.

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