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

Package com.sas.services.publish

# Interface ResultPackageInterface

All Superinterfaces:
  `com.sas.entities.EntityKeyInterface`, `EntryInterface`, `com.sas.io.InputStreamProviderInterface`, `Remote`

All Known Implementing Classes:
  `ResultPackage`

@SASScope("ALL") @BinaryCompatibilityOnly public interface ResultPackageInterface extends EntryInterface, com.sas.io.InputStreamProviderInterface, 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

  Modifier and Type
  Method
  Description
  `void`
  `addEntry(EntryInterface entry)`
  Adds a new entry to the result package.
  `void`
  `close()`
  Close the result package.
  `void`
  `delete()`
  Delete the result package.
  `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(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.
  `InputStream`
  `getInputStream()`
  Gets the input stream for this result package.
  `InputStream`
  `getInputStream(Object streamID)`
  Deprecated.
  Use `getInputStream()` which now supports remote input streams.
  `String`
  `getName()`
  Returns the name for this result package.
  `com.sas.io.RemoteInputStreamInterface`
  `getRemoteInputStream(Object streamID)`
  Deprecated.
  Use `getInputStream()` which now supports remote input streams.
  `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(String description)`
  Set the abstract for the result package.
  `void`
  `setExpirationDateTime(long expiration)`
  Sets the expiration datetime stamp for the result package.
  `void`
  `setName(String name)`
  Set the name for the result package.

  ### Methods inherited from interface com.sas.entities.EntityKeyInterface

  `getEntityKey, sameEntity, setEntityKey`

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

  `getDescription, getNameValuePairs, getURL, isReadOnly, setDescription, setNameValuePairs`

- ## Method Details

  - ### getAbstract

    String getAbstract() throws IllegalStateException, TransportException, RemoteException
    Returns the abstract of the result package.
    Returns:
      `String` The abstract of the result package; can be `null`.
    Throws:
      `IllegalStateException` - If the result package has already been closed.
      `TransportException` - If the transport encounters an error getting the abstract.
      `RemoteException` - If a network anomaly is encountered.

  - ### setAbstract

    void setAbstract(String description) throws IllegalStateException, RemoteException
    Set the abstract for the result package.
    Parameters:
      `description` - Plain text that is the abstract for this result package.
    Throws:
      `IllegalStateException` - If the result package is read only or the result package has already been closed.
      `RemoteException` - If a network anomaly is encountered.

  - ### getExpirationDateTime

    long getExpirationDateTime() throws IllegalStateException, TransportException, 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:
      `IllegalStateException` - If the result package has already been closed.
      `TransportException` - If the transport encounters an error getting the expiration datetime stamp.
      `RemoteException` - If a network anomaly is encountered.

  - ### setExpirationDateTime

    void setExpirationDateTime(long expiration) throws IllegalStateException, 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:
      `IllegalStateException` - If the result package is read only or the result package has already been closed.
      `RemoteException` - If a network anomaly is encountered.

  - ### getCreationDateTime

    long getCreationDateTime() throws IllegalStateException, TransportException, 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:
      `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.
      `RemoteException` - If a network anomaly is encountered.

  - ### getName

    String getName() throws IllegalStateException, TransportException, 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:
      `IllegalStateException` - If the result package has already been closed.
      `TransportException` - If the transport encounters an error getting the nested name.
      `RemoteException` - If a network anomaly is encountered.

  - ### setName

    void setName(String name) throws IllegalStateException, 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:
      `IllegalStateException` - If the result package is read only or the result package has already been closed.
      `RemoteException` - If a network anomaly is encountered.

  - ### getEntry

    EntryInterface getEntry(int index) throws IllegalStateException, 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:
      `IllegalStateException` - If the result package has already been closed.
      `TransportException` - If the transport encounters an error getting the entry.
      `RemoteException` - If a network anomaly is encountered.

  - ### getEntry

    EntryInterface getEntry(String uniqueId) throws IllegalStateException, 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:
      `IllegalStateException` - If the result package has already been closed.
      `TransportException` - If the transport encounters an error getting the entry.
      `RemoteException` - If a network anomaly is encountered.

  - ### getEntries

    EntryInterface[] getEntries() throws IllegalStateException, 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:
      `IllegalStateException` - If the result package has already been closed.
      `TransportException` - If the transport encounters an error getting the entry.
      `RemoteException` - If a network anomaly is encountered.

  - ### addEntry

    void addEntry(EntryInterface entry) throws IllegalStateException, 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:
      `IllegalStateException` - If the result package is read only or the result package has already been closed.
      `RemoteException` - If a network anomaly is encountered.

  - ### isNested

    boolean isNested() throws RemoteException, 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:
      `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.
      `RemoteException` - If a network anomaly is encountered.

  - ### close

    void close() throws IllegalStateException, TransportException, 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:
      `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.
      `RemoteException` - If a network anomaly is encountered.

  - ### delete

    void delete() throws UnsupportedOperationException, TransportException, 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:
      `UnsupportedOperationException` - If the operation is not supported by the transport.
      `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.
      `RemoteException` - If a network anomaly is encountered.

  - ### getEventData

    EventDataInterface getEventData() throws TransportException, 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.
      `RemoteException` - If a network anomaly is encountered.

  - ### getInputStream

    InputStream getInputStream(Object streamID) throws UnmarshalException, IOException, RemoteException, 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:
      `UnmarshalException` - If invoked on a remote object.
      `IOException` - If an error occurs constructing the input stream.
      `RemoteException` - If a network anomaly is encountered.
      `IllegalStateException` - If the package containing this entry is already closed.

  - ### getRemoteInputStream

    com.sas.io.RemoteInputStreamInterface getRemoteInputStream(Object streamID) throws IOException, RemoteException, 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:
      `IOException` - If an error occurs constructing the remote input stream.
      `RemoteException` - If a network anomaly is encountered.
      `IllegalStateException` - If the package containing this entry is already closed.

  - ### getInputStream

    InputStream getInputStream() throws IOException, RemoteException, 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:
      `IOException` - If an error occurs constructing the input stream.
      `RemoteException` - If a network anomaly is encountered.
      `IllegalStateException` - If the package containing this entry is already closed.

  - ### hasInputStream

    Object hasInputStream() throws UnmarshalException, 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:
      `UnmarshalException` - if invoked on a remote obejct
      `RemoteException` - if a network anomaly is encountered.
      `IllegalStateException` - if this result package has already been closed.