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