All Known Implementing Classes:

FolderExportContainer, ZIPExportContainer
```
public interface ExportContainer
```
An export container represents a file or file system that can contain a collection of exported files. For example, a container might store exported files in a ZIP archive or a folder. One application of export containers is the export command used with game components. This command displays a dialog that allows the user to choose how the component will be exported by selecting any one of the registered containers.
Export containers are registered with the application for use by anyone wanting to export a collection of files. To get the available containers, call StrangeEons.getRegisteredExportContainers(). Plug-ins can create new kinds of containers and register them by calling StrangeEons.registerExportContainer(ca.cgjennings.apps.arkham.ExportContainer). To use an export container, follow these steps:
1. Call selectLocation(java.lang.String, java.awt.Component) to allow the user to select a destination for the container or perform other configuration steps. If this returns false, cancel the export.
2. Call createContainer() to start the export process by creating the container.
3. Call addEntry(java.lang.String) once for each file to be written. For each call, write the file to the provided output stream (closing the stream when done).
4. Call closeContainer(boolean) once all files have been written.
Once a container has been created, you must either close it or destroy it before a new container can be created. The following Java code pattern is illustrates the process:
```
 ExportContainer ec = theExportContainerToUse;
 ec.selectLocation( baseName );
 ec.createContainer();
 try {
     // write files to the container
     while( moreFilesToWrite ) {
         OutputStream out = ec.addEntry( "file name " + n );
         try {
             // write file data to output stream
         } finally {
             out.close();
         }
     }
     ec.closeContainer(false);
 } catch( Throwable t ) {
     ec.destroyContainer();
     // handle or throw exception
 }
 
```
Note that there is typically only one instance of a given export container that is shared by all users. It is therefore vital that users of a contain surround its use with appropriate try ... catch blocks. Otherwise, an error may leave the container instance in an invalid state and it will not be usable again until the application is restarted.
Since:

3.0

Author:

Chris Jennings

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`java.io.OutputStream`	`addEntry(java.lang.String name)`	Creates a new file in the container with the given name and returns an output stream for the caller to write the file to.
`void`	`closeContainer(boolean display)`	Close the current container, allowing a new container to be created.
`void`	`configure(java.awt.Component locationHint)`	Show a dialog allow the user to configure the container options.
`void`	`createContainer()`	Begins an export operation by creating an empty container.
`void`	`destroyContainer()`	Destroys the current container instead of closing it.
`java.lang.String`	`getIdentifier()`	Returns an identifier unique to this container type.
`boolean`	`isConfigurable()`	Returns `true` if the container has user-configurable options.
`boolean`	`isFileFormatSupported(java.lang.String extension)`	Returns a hint as to whether a file format is supported.
`boolean`	`selectLocation(java.lang.String baseName, java.awt.Component locationHint)`	Displays a dialog that allows the user to select a destination for the container.
`void`	`setLocation(java.io.File location)`	This method can be used to set an explicit location for the container instead of asking the user to select a location.
`java.lang.String`	`toString()`	Returns a description of the container format, ideally in the user interface locale.

- Method Detail
  - getIdentifier
```
java.lang.String getIdentifier()
```
    Returns an identifier unique to this container type. It is never shown to the user and must not be localized; it is used to identify the user's preferred container in user settings.
    
    Returns:
    
    a unique identifier for the container
  - toString
```
java.lang.String toString()
```
    Returns a description of the container format, ideally in the user interface locale.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a description of the container, such as "ZIP Archive"
  - selectLocation
```
boolean selectLocation(java.lang.String baseName,
                       java.awt.Component locationHint)
```
    Displays a dialog that allows the user to select a destination for the container. The dialog is not necessarily a file dialog; for example, it might prompt the user to enter account credentials for an online service or enter the address of an FTP server. It is not required to show any dialog at all, and may simply return true if there is nothing for the user to decide.
    
    Parameters:
    
    baseName - a suggested base name that can be used to compose a file or folder name for the container
    
    locationHint - an optional component that may be used as a hint to locate any dialogs that must be created
    
    Returns:
    
    true if the export should proceed, or false if the user cancels the operation
  - setLocation
```
void setLocation(java.io.File location)
```
    This method can be used to set an explicit location for the container instead of asking the user to select a location. It can only work with containers that write to the local file system, such as FolderExportContainer and ZIPExportContainer. The method is provided for testing and for use with explicitly created containers.
    
    Parameters:
    
    location - the parent folder where the container should be created
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the container type does not support creating containers in the file system
  - createContainer
```
void createContainer()
              throws java.io.IOException
```
    Begins an export operation by creating an empty container.
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
  - addEntry
```
java.io.OutputStream addEntry(java.lang.String name)
                       throws java.io.IOException
```
    Creates a new file in the container with the given name and returns an output stream for the caller to write the file to. After writing the file, you are responsible for calling close() on the output stream.
    
    Parameters:
    
    name - the name of the file to create in the container
    
    Returns:
    
    an output stream to which the "file" should be written
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
  - closeContainer
```
void closeContainer(boolean display)
             throws java.io.IOException
```
    Close the current container, allowing a new container to be created.
    
    Parameters:
    
    display - if true, the user has requested that the container be "displayed"
    
    Throws:
    
    java.io.IOException - if an I/O exception occurs
  - destroyContainer
```
void destroyContainer()
```
    Destroys the current container instead of closing it. This can be called instead of closeContainer(boolean) if an I/O error occurs while writing the container. Ideally, it should delete the partially-created container.
  - isConfigurable
```
boolean isConfigurable()
```
    Returns true if the container has user-configurable options.
    
    Returns:
    
    true if the container can be configure(java.awt.Component)d
  - configure
```
void configure(java.awt.Component locationHint)
```
    Show a dialog allow the user to configure the container options.
    
    Parameters:
    
    locationHint - an optional hint as to where to locate the dialog
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the container isn't configurable
  - isFileFormatSupported
```
boolean isFileFormatSupported(java.lang.String extension)
```
    Returns a hint as to whether a file format is supported. This method returns true if the file type is definitely supported. It returns false if the file type is not supported, or if the container cannot determine whether the file type is supported.
    A common use of this method is to determine whether a container is compatible with some kind of task being presented to the user. In these cases, implementations that always return false will not be included in the list of container choices presented to the user.
    Some export containers may not support files in some formats: while a ZIP archive can hold any kind of file, an image hosting service might only accept, say, PNG and JPG images. This method allows an export container to return a hint to exporters as to whether a file format is compatible with the container. To use it, the caller passes in a string representing the typical file name extension for files of the format in question.
    Note that the addEntry(java.lang.String) method is required to accept any content that it is given, but an export container may choose to do anything it wishes with unsupported formats. For example, it may skip the file by returning a dummy output stream. Or it may accept the file but silently convert it into an acceptable format. (The documentation for the container should specify how unsupported files are handled.)
    
    Parameters:
    
    extension - the typical file format extension for the file, such as "png" for PNG images
    
    Returns:
    
    true if the file type is definitely supported, and false otherwise

Interface ExportContainer

Method Summary

Method Detail

getIdentifier

toString

selectLocation

setLocation

createContainer

addEntry

closeContainer

destroyContainer

isConfigurable

configure

isFileFormatSupported