Adding an Archive Type

An archive type is an abstraction of the archive file format. An archive type can be implemented as a plain JAR file, as a directory layout, or a custom type. By default, Enterprise Server recognizes JAR based and directory based archive types. A new container might require a new archive type.

There are two sub-interfaces of the org.glassfish.api.deployment.archive.Archive interface, org.glassfish.api.deployment.archive.ReadableArchive and org.glassfish.api.deployment.archive.WritableArchive. Typically developers of new archive types will provide separate implementations of ReadableArchive and WritableArchive, or a single implementation that implements both ReadableArchive and WritableArchive.

Implementations of the ReadableArchive interface provide read access to an archive type. ReadableArchive defines the following methods:

getEntry(String name)

Returns a java.io.InputStream for the specified entry name, or null if the entry doesn't exist.

exists(String name)

Returns a boolean value indicating whether the specified entry name exists.

getEntrySize(String name)

Returns the size of the specified entry as a long value.

open(URI uri)

Returns an archive for the given java.net.URI.

getSubArchive(String name)

Returns an instance of ReadableArchive for the specified sub-archive contained within the parent archive, or null if no such archive exists.

exists()

Returns a boolean value indicating whether this archive exists.

delete()

Deletes the archive, and returns a boolean value indicating whether the archive has been successfully deleted.

renameTo(String name)

Renames the archive to the specified name, and returns a boolean value indicating whether the archive has been successfully renamed.

Implementations of the WritableArchive interface provide write access to the archive type. WritableArchive defines the following methods:

create(URI uri)

Creates a new archive with the given path, specified as a java.net.URI.

closeEntry(WritableArchive subArchive)

Closes the specified sub-archive contained within the parent archive.

closeEntry()

Closes the current entry.

createSubArchive(String name)

Creates a new sub-archive in the parent archive with the specified name, and returns it as a WritableArchive instance.

putNextEntry(String name)

Creates a new entry in the archive with the specified name, and returns it as a java.io.OutputStream.

Implementing the ArchiveHandler Interface

An archive handler is responsible for handling the particular layout of an archive. Java EE defines a set of archives (WAR, JAR, and RAR, for example), and each of these archives has an ArchiveHandler instance associated with the archive type.

Each layout should have one handler associated with it. There is no extension point support at this level; the archive handler's responsibility is to give access to the classes and resources packaged in the archive, and it should not contain any container-specific code. The java.lang.ClassLoader returned by the handler is used by all the containers in which the application will be deployed.

ArchiveHandler defines the following methods:

getArchiveType()

Returns the name of the archive type as a String. Typically, this is the archive extension, such as jar or war.

getDefaultApplicationName(ReadableArchive archive)

Returns the default name of the specified archive as a String. Typically this default name is the name part of the URI location of the archive.

handles(ReadableArchive archive)

Returns a boolean value indicating whether this implementation of ArchiveHandler can work with the specified archive.

getClassLoader(DeploymentContext dc)

Returns a java.lang.ClassLoader capable of loading all classes from the archive passed in by the DeploymentContext instance. Typically the ClassLoader will load classes in the scratch directory area, returned by DeploymentContext.getScratchDir(), as stubs and other artifacts are generated in the scratch directory.

expand(ReadableArchive source, WritableArchive target)

Prepares the ReadableArchivesource archive for loading into the container in a format the container accepts. Such preparation could be to expand a compressed archive, or possibly nothing at all if the source archive format is already in a state that the container can handle. This method returns the archive as an instance of WritableArchive.