All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Foundation |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

*** 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 ***

All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Foundation |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 SAS Institute Inc. All Rights Reserved.