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

Package com.sas.services.publish

# Class HTMLFile

java.lang.Object
java.rmi.server.RemoteObject
java.rmi.server.RemoteServer
java.rmi.server.UnicastRemoteObject
com.sas.services.publish.HTMLFile

All Implemented Interfaces:
  `com.sas.entities.EntityKeyInterface`, `com.sas.io.InputStreamProviderInterface`, `HTMLFileInterface`, `Serializable`, `Remote`

@SASScope("ALL") @BinaryCompatibilityOnly public class HTMLFile extends UnicastRemoteObject implements HTMLFileInterface
The HTMLFileInterface provides a mechanism for setting and getting the attributes of a file contained within an HTML entry.

Files that implement HTMLFileInterface can be inserted into an HTML entry. `HTMLEntryInterface`is a container for various files that implement HTMLFileInterface. Within MVA SAS, the ODS HTML statement generates HTML files. The body file contains the results from the procedure. The contents file is a table of contents that links to the body file. The pages file is a table of pages that links to the body file. The frame file is a frame that displays the table of contents, the table of pages and the body file. The HTML entry provides a way to identify each of these files, and encapsulate them into one entry.

The HTML file is limited to just one role. One file should be designated as the main file for the HTML entry. The main file identifies which file in the HTML entry should be used as the starting point when browsing the HTML entry. The main file will have a role of `HTMLFileInterface.MAIN_BODY_FILE`or `HTMLFileInterface.MAIN_FRAME_FILE`. If a frame file exists, it should be designated as the main file; otherwise, the body file should be designated as the main file. All other files are considered companion files. The companion files are any files other than the main HTML file. The companion files can include, body, frame, contents and page files, as well as any miscellaneous files (such as HTML, GIF, JPG) needed by the HTML entry. Supported companion roles include `HTMLFileInterface.FRAME_COMPANION`,`HTMLFileInterface.BODY_COMPANION`, `HTMLFileInterface.PAGE_COMPANION`,`HTMLFileInterface.CONTENTS_COMPANION`, `HTMLFileInterface.MISC_COMPANION`.

Since:
  1.0
See Also:
  - `HTMLEntry`
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class java.rmi.server.RemoteObject

  `ref`

  ### Fields inherited from interface com.sas.services.publish.HTMLFileInterface

  `BODY_COMPANION, CONTENTS_COMPANION, FRAME_COMPANION, MAIN_BODY_FILE, MAIN_FRAME_FILE, MISC_COMPANION, PAGE_COMPANION`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `HTMLFile()`
  Constructs a default instance.
  ``
  `HTMLFile(File file, int role)`
  Creates an HTML file or companion file.
  ``
  `HTMLFile(InputStream inputStream, String name, int role)`
  Creates an HTML file or companion file.
  `protected`
  `HTMLFile(Class theClass)`
  Constructs an instance using RMI socket factories appropriate for the specified class.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `closeEntry()`
  Remove any temporary files needed for inputstream re-use.
  `void`
  `consumeStream()`
  Consume and close the input stream provided on the constructor.
  `protected void`
  `finalize()`
  At finalize time, cleanup temporary files if necessary.
  `String`
  `getEncoding()`
  Returns the encoding for this file.
  `String`
  `getEntityKey()`
  Get the unique identifier of this result package or entry.
  `InputStream`
  `getInputStream()`
  Gets the input stream for this file.
  `InputStream`
  `getInputStream(Object streamID)`
  Deprecated.
  Use `getInputStream()`which now supports remote input streams.
  `String`
  `getMIMEType()`
  Returns the MIME type of the file.
  `String`
  `getName()`
  Returns the name of the file.
  `com.sas.io.RemoteInputStreamInterface`
  `getRemoteInputStream(Object streamID)`
  Deprecated.
  Use `getInputStream()`which now supports remote input streams.
  `int`
  `getRole()`
  Returns the role of this file within the HTML entry.
  `String`
  `getURL()`
  Returns the URL for this file.
  `Object`
  `hasInputStream()`
  Deprecated.
  this method no longer needed as getInputStream() will return an input stream that can be used in a remote environment
  `boolean`
  `isReadOnly()`
  Returns true when the entry is read only.
  `boolean`
  `sameEntity(com.sas.entities.EntityKeyInterface entity)`
  `void`
  `setEncoding(String encoding)`
  Sets the file encoding.
  `void`
  `setEntityKey(String entityKey)`
  Set the unique entity key.
  `void`
  `setMIMEType(String mimeType)`
  Sets the MIME type associated with this file; can be null.
  `void`
  `setURL(String url)`
  Sets the URL of the file.

  ### Methods inherited from class java.rmi.server.UnicastRemoteObject

  `clone, exportObject, exportObject, exportObject, exportObject, exportObject, unexportObject`

  ### Methods inherited from class java.rmi.server.RemoteServer

  `getClientHost, getLog, setLog`

  ### Methods inherited from class java.rmi.server.RemoteObject

  `equals, getRef, hashCode, toString, toStub`

  ### Methods inherited from class java.lang.Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### HTMLFile

    public HTMLFile() throws RemoteException
    Constructs a default instance. A public constructor is provided since the compiler has been previosly generating a default public constructor. Use `HTMLFile(File file, int role)`instead of this constructor.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### HTMLFile

    protected HTMLFile(Class theClass) throws RemoteException
    Constructs an instance using RMI socket factories appropriate for the specified class.
    Parameters:
      `theClass` - The class to use when determine which RMI socket factories are to be used when exporting a remote object.
    Throws:
      `RemoteException` - if unable to export the remote object.

  - ### HTMLFile

    public HTMLFile(File file, int role) throws IllegalArgumentException, RemoteException
    Creates an HTML file or companion file. When the file is published, the file name is used as the name. If a different name is preferred, use the constructor that takes the input stream and the name of the entry.

    There is no default MIME type. To set the MIME type for the entry, use `setMIMEType(String)`.

    Parameters:
      `file` - The file.
      `role` - The role of the file. Valid roles include `HTMLFileInterface.MAIN_BODY_FILE`,`HTMLFileInterface.MAIN_FRAME_FILE`, `HTMLFileInterface.BODY_COMPANION`,`HTMLFileInterface.FRAME_COMPANION`, `HTMLFileInterface.CONTENTS_COMPANION`,`HTMLFileInterface.PAGE_COMPANION`or `HTMLFileInterface.MISC_COMPANION`.
    Throws:
      `IllegalArgumentException` - If a `null` file or invalid file type is specified.
      `RemoteException` - If a network anomaly is encountered.

  - ### HTMLFile

    public HTMLFile(InputStream inputStream, String name, int role) throws IllegalArgumentException, RemoteException
    Creates an HTML file or companion file. When the file is published, the input stream will be consumed until end-of-file.

    There is no default MIME type. To set the MIME type for the entry, use `setMIMEType(String)`.

    Parameters:
      `inputStream` - The input stream of the HTML or companion file.
      `name` - The name of the HTML or companion file. When an HTML file is published, the URL is used to publish the file, if it was specified. If the URL is not specified, this name will be used as the name of the file.
      `role` - The role of the file. Valid roles include `HTMLFileInterface.MAIN_BODY_FILE`,`HTMLFileInterface.MAIN_FRAME_FILE`, `HTMLFileInterface.BODY_COMPANION`,`HTMLFileInterface.FRAME_COMPANION`, `HTMLFileInterface.CONTENTS_COMPANION`,`HTMLFileInterface.PAGE_COMPANION`or `HTMLFileInterface.MISC_COMPANION`.
    Throws:
      `IllegalArgumentException` - If a `null` input stream, a `null` name, or an invalid file type is specified.
      `RemoteException` - If a network anomaly is encountered.

- ## Method Details

  - ### getURL

    public String getURL() throws RemoteException
    Returns the URL for this file.
    Specified by:
      `getURL` in interface `HTMLFileInterface`
    Returns:
      `String` The URL for the file.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### setURL

    public void setURL(String url) throws IllegalStateException, RemoteException
    Sets the URL of the file.
    Specified by:
      `setURL` in interface `HTMLFileInterface`
    Parameters:
      `url` - The URL for the file.
    Throws:
      `IllegalStateException` - If the entry is read only.
      `RemoteException` - If a network anomaly is encountered.

  - ### getEncoding

    public String getEncoding() throws RemoteException
    Returns the encoding for this file.
    Specified by:
      `getEncoding` in interface `HTMLFileInterface`
    Returns:
      `String` The encoding for this file.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### setEncoding

    public void setEncoding(String encoding) throws IllegalStateException, RemoteException
    Sets the file encoding.
    Specified by:
      `setEncoding` in interface `HTMLFileInterface`
    Parameters:
      `encoding` - The encoding of the file.
    Throws:
      `IllegalStateException` - If the entry is read only.
      `RemoteException` - If a network anomaly is encountered.

  - ### isReadOnly

    public boolean isReadOnly() throws RemoteException
    Returns true when the entry is read only. Entries are read only if they belong to an existing package that is being retrieved.
    Returns:
      `boolean` `True` if read only; otherwise if this is a new entry/package under construction, `false` is returned.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### getName

    public String getName() throws RemoteException
    Returns the name of the file.
    Specified by:
      `getName` in interface `HTMLFileInterface`
    Returns:
      `String` The name of the file.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### getMIMEType

    public String getMIMEType()
    Returns the MIME type of the file.
    Specified by:
      `getMIMEType` in interface `HTMLFileInterface`
    Returns:
      `String` The MIME type of the file.

  - ### setMIMEType

    public void setMIMEType(String mimeType) throws IllegalStateException, RemoteException
    Sets the MIME type associated with this file; can be null.
    Specified by:
      `setMIMEType` in interface `HTMLFileInterface`
    Parameters:
      `mimeType` - The MIME type associated with this file.
    Throws:
      `IllegalStateException` - If the entry is read only.
      `RemoteException` - If a network anomaly is encountered.

  - ### getRole

    public int getRole() throws RemoteException
    Returns the role of this file within the HTML entry.
    Specified by:
      `getRole` in interface `HTMLFileInterface`
    Returns:
      `int` The role of the file. Supported types include `BODY_COMPANION`, `FRAME_COMPANION`, `CONTENTS_COMPANION`, `PAGE_COMPANION`and `MISC_COMPANION`.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### getInputStream

    public InputStream getInputStream() throws IOException, RemoteException
    Gets the input stream for this file.
    Specified by:
      `getInputStream` in interface `HTMLFileInterface`
    Returns:
      The input stream that can be used for reading the contents of the binary file entry.
    Throws:
      `IOException` - If an error occurs constructing the input stream.
      `RemoteException` - If a network anomaly is encountered.

  - ### getInputStream

    public InputStream getInputStream(Object streamID) throws IOException, RemoteException, UnmarshalException
    Deprecated.
    Use `getInputStream()`which now supports remote input streams.
    Gets the input stream for this file. 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(Object)`in order to obtain the input stream.
    Specified by:
      `getInputStream` in interface `HTMLFileInterface`
    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 binary file entry.
    Throws:
      `UnmarshalException` - If invoked on a remote object.
      `IOException` - If an error occurs constructing the input stream.
      `RemoteException` - If a network anomaly is encountered.

  - ### getRemoteInputStream

    public com.sas.io.RemoteInputStreamInterface getRemoteInputStream(Object streamID) throws com.sas.io.ChainedIOException, RemoteException
    Deprecated.
    Use `getInputStream()`which now supports remote input streams.
    Get the a remote input stream.
    Specified by:
      `getRemoteInputStream` in interface `HTMLFileInterface`
    Specified by:
      `getRemoteInputStream` in interface `com.sas.io.InputStreamProviderInterface`
    Parameters:
      `streamID` - The stream description should be `null` ;it will be ignored.
    Returns:
      `RemoteInputStream` The file as a remote input stream.
    Throws:
      `com.sas.io.ChainedIOException` - If an I/O error occurs obtaining the remote input stream.
      `RemoteException` - If a network anomaly is encountered.

  - ### hasInputStream

    public 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 `HTMLFileInterface`
    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.

  - ### consumeStream

    public void consumeStream() throws IOException, RemoteException, IllegalStateException
    Consume and close the input stream provided on the constructor. If an input stream is provided on the entry's constructor, then it does not get consumed until the package is published. This method may be invoked to force the stream to get consumed and closed immediately instead of waiting until the publish occurs.
    Throws:
      `IllegalStateException` - If the package containing this entry is already closed.
      `IOException` - If an error occurs constructing the input stream.
      `RemoteException` - If a network anomaly is encountered.

  - ### getEntityKey

    public String getEntityKey() throws IllegalStateException, RemoteException
    Get the unique identifier of this result package or entry.
    Specified by:
      `getEntityKey` in interface `com.sas.entities.EntityKeyInterface`
    Returns:
      `String` The unique identifier.
    Throws:
      `RemoteException` - If a network anomaly is encountered.
      `IllegalStateException`

  - ### sameEntity

    public boolean sameEntity(com.sas.entities.EntityKeyInterface entity) throws RemoteException
    Specified by:
      `sameEntity` in interface `com.sas.entities.EntityKeyInterface`
    Throws:
      `RemoteException`

  - ### setEntityKey

    public void setEntityKey(String entityKey) throws RemoteException, IllegalStateException
    Set the unique entity key. The entity key for the result package or entry cannot be changed. This method will throw an IllegalStateException.
    Specified by:
      `setEntityKey` in interface `com.sas.entities.EntityKeyInterface`
    Parameters:
      `entityKey` - Unique entity key.
    Throws:
      `IllegalStateException` - The unique entity key for a result package or entry cannot be changed.
      `RemoteException`

  - ### closeEntry

    protected void closeEntry()
    Remove any temporary files needed for inputstream re-use.

  - ### finalize

    protected void finalize() throws Throwable
    At finalize time, cleanup temporary files if necessary.
    Overrides:
      `finalize` in class `Object`
    Throws:
      `Throwable`