Interface ExportContainer
-
- 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 callingStrangeEons.registerExportContainer(ca.cgjennings.apps.arkham.ExportContainer)
. To use an export container, follow these steps:- 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 returnsfalse
, cancel the export. - Call
createContainer()
to start the export process by creating the container. - 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). - 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()
Returnstrue
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 classjava.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 returntrue
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 containerlocationHint
- 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, orfalse
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 asFolderExportContainer
andZIPExportContainer
. 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 callingclose()
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
- iftrue
, 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 ofcloseContainer(boolean)
if an I/O error occurs while writing the container. Ideally, it should delete the partially-created container.
-
isConfigurable
boolean isConfigurable()
Returnstrue
if the container has user-configurable options.- Returns:
true
if the container can beconfigure(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 returnstrue
if the file type is definitely supported. It returnsfalse
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, andfalse
otherwise
-
-