All Superinterfaces:: Assignable

All Known Subinterfaces:: EnterpriseArchive, GenericArchive, JavaArchive, ResourceAdapterArchive, WebArchive

public interface Archive<T extends Archive<T>> extends Assignable

Represents a collection of resources which may be constructed programmatically. In effect this represents a virtual filesystem.

All Archive types support the addition of Nodes under a designated ArchivePath (context). The contents of a Node are either a directory or Asset.

Archives are generally created via an ArchiveFactory or via the default configuration shortcut ShrinkWrap utility class.

Because Archives are Assignable, they may be wrapped in another user "view" used to perform operations like adding JavaEE Spec-specific resources or exporting in ZIP format.

Version:: $Revision: $
Author:: ALR

Method Summary

Modifier and Type

Method

Description

T

add(Archive<?> archive, String path, Class<? extends StreamExporter> exporter)

Add an archive under a specific context and maintain the archive name as context path.

T

add(Archive<?> archive, ArchivePath path, Class<? extends StreamExporter> exporter)

Add an archive under a specific context and maintain the archive name as context path.

T

add(Asset asset, String target)

Adds the specified asset under the context denoted by the specified target

T

add(Asset asset, String target, String name)

Adds the specified asset under the specified target (directory) using the specified name.

T

add(Asset asset, ArchivePath target)

Adds the specified asset under the specified path into the target context

T

add(Asset asset, ArchivePath target, String name)

Adds the specified asset under the specified target (directory) using the specified name.

T

add(NamedAsset namedAsset)

Adds the asset encapsulated within the specified NamedAsset under the encapsulated name and target (directory)

T

addAsDirectories(String... paths)

Adds the specified directories.

T

addAsDirectories(ArchivePath... paths)

Adds the specified directories.

T

addAsDirectory(String path)

Adds the specified directory.

T

addAsDirectory(ArchivePath path)

Adds the specified directory.

T

addHandlers(ArchiveEventHandler... handlers)

Adds an array of handlers for callback-based operations.

boolean

contains(String path)

Denotes whether this archive contains a resource at the specified path

boolean

contains(ArchivePath path)

Denotes whether this archive contains a resource at the specified path

Node

delete(String archivePath)

Removes the Node in the Archive at the ArchivePath indicated by the specified String archivePath.

Node

delete(ArchivePath path)

Removes the Node in the Archive at the specified ArchivePath.

T

filter(Filter<ArchivePath> filter)

Obtains all assets matching given filter in this archive as a new Archive.

This is an alias for shallowCopy(Filter).

Node

get(String path)

Obtains the Node located at the specified path

Node

get(ArchivePath path)

Obtains the Node located at the specified path

<X extends Archive<X>> X

getAsType(Class<X> type, String path)

Get a nested Archive as a specific type.

The found Archives must have been added as an Archive, no import is performed.

<X extends Archive<X>> X

getAsType(Class<X> type, String path, ArchiveFormat archiveFormat)

Get a nested Archive as a specific type using the specified ArchiveFormat

<X extends Archive<X>> X

getAsType(Class<X> type, ArchivePath path)

Get a nested Archive as a specific type.

The found Archives must have been added as an Archive, no import is performed.

<X extends Archive<X>> X

getAsType(Class<X> type, ArchivePath path, ArchiveFormat archiveFormat)

Get a nested Archive located in a ArchivePath as a specific type using the specified ArchiveFormat

<X extends Archive<X>> Collection<X>

getAsType(Class<X> type, Filter<ArchivePath> filter)

Get all nested Archive matching the filter as a specific type.

The found Archives must have been added as an Archive, no import is performed.

<X extends Archive<X>> Collection<X>

getAsType(Class<X> type, Filter<ArchivePath> filter, ArchiveFormat archiveFormat)

Get all nested Archive matching the filter as a specific type using the specified ArchiveFormat.

Map<ArchivePath, Node>

getContent()

Obtains all assets in this archive, along with their respective paths.

Map<ArchivePath, Node>

getContent(Filter<ArchivePath> filter)

Obtains all assets matching given filter in this archive, along with its respective Path.

String

getId()

Obtains a globally-unique identifier for this Archive

String

getName()

Obtains the name of this archive (i.e.

T

merge(Archive<?> source)

Merge the contents from an existing archive without maintaining the archive name in the context path.

T

merge(Archive<?> source, String path)

Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path.

T

merge(Archive<?> source, String path, Filter<ArchivePath> filter)

Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path.

T

merge(Archive<?> source, ArchivePath path)

Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path.

T

merge(Archive<?> source, ArchivePath path, Filter<ArchivePath> filter)

Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path.

T

merge(Archive<?> source, Filter<ArchivePath> filter)

Merge the contents from an existing archive without maintaining the archive name in the context path.

T

move(String source, String target)

Moves the asset under the source path to the target path.

T

move(ArchivePath source, ArchivePath target)

Moves the asset under the source path to the target path.

Archive<T>

shallowCopy()

Creates a shallow copy of this Archive.

Archive<T>

shallowCopy(Filter<ArchivePath> filter)

Creates a shallow copy of this Archive based on given filter.

String

toString()

Acts as a shorthand for toString(Formatter) where the Formatters.SIMPLE is leveraged.

String

toString(boolean verbose)

If "true" is specified, acts as a shorthand for toString(Formatter) where the Formatters.VERBOSE is leveraged.

String

toString(Formatter formatter)

Returns a view of this Archive as returned from the specified Formatter.

void

writeTo(OutputStream outputStream, Formatter formatter)

Prints the content of this Archive to the specified OutputStream on the format defined by the specified Formatter.

Methods inherited from interface Assignable
as

Method Details
- getName
  
  String getName()
  
  Obtains the name of this archive (i.e. myLibrary.jar)
  
  Returns:
  
  The name of the archive
- getId
  
  String getId()
  
  Obtains a globally-unique identifier for this Archive
  
  Returns:
  
  The globally-unique identifier for the archive
- add
  
  T add(Asset asset, ArchivePath target) throws IllegalArgumentException
  
  Adds the specified asset under the specified path into the target context
  If an asset already exists at the specified path, it will be replaced.
  
  Parameters:
  
  asset - The asset to add
  
  target - The context under which to add the asset
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If no target or asset were specified
  
  IllegalArchivePathException - If the target is invalid.
- add
  
  T add(Asset asset, ArchivePath target, String name) throws IllegalArgumentException
  
  Adds the specified asset under the specified target (directory) using the specified name. The resultant path will treat the specified path as a prefix namespace, then append the name.
  If an asset already exists at the specified path, it will be replaced.
  
  Parameters:
  
  asset - The asset to add
  
  target - The context directory under which to add the asset
  
  name - The name to assign the asset under the target namespace
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the target, name, or asset was not specified
  
  IllegalArchivePathException - If the target is invalid.
- add
  
  T add(Asset asset, String target, String name) throws IllegalArgumentException
  
  Adds the specified asset under the specified target (directory) using the specified name. The resultant path will treat the specified path as a prefix namespace, then append the name.
  If an asset already exists at the specified path, it will be replaced.
  
  Parameters:
  
  asset - The asset to add
  
  target - The context directory under which to add the asset
  
  name - The name to assign the asset under the target namespace
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the target, name, or asset was not specified
  
  IllegalArchivePathException - If the target is invalid.
- add
  
  T add(NamedAsset namedAsset) throws IllegalArgumentException
  
  Adds the asset encapsulated within the specified NamedAsset under the encapsulated name and target (directory)
  If an asset already exists at the specified path, it will be replaced.
  
  Parameters:
  
  namedAsset - The named asset to add
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If either the target or asset is not specified
  
  IllegalArchivePathException - If the target is invalid.
- add
  
  T add(Asset asset, String target) throws IllegalArgumentException
  
  Adds the specified asset under the context denoted by the specified target
  If an asset already exists at the specified path, it will be replaced.
  
  Parameters:
  
  asset - The asset to add
  
  target - The context under which to add the asset
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If either the target or asset is not specified
  
  IllegalArchivePathException - If the target is invalid.
- addAsDirectory
  
  T addAsDirectory(String path) throws IllegalArgumentException
  
  Adds the specified directory.
  
  Parameters:
  
  path - The path to add
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If no path was specified
  
  IllegalArchivePathException - If the path is invalid.
- addAsDirectories
  
  T addAsDirectories(String... paths) throws IllegalArgumentException
  
  Adds the specified directories.
  
  Parameters:
  
  paths - The paths to add
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If no paths were specified
  
  IllegalArchivePathException - If at least one path is invalid.
- addAsDirectory
  
  T addAsDirectory(ArchivePath path) throws IllegalArgumentException
  
  Adds the specified directory.
  
  Parameters:
  
  path - The path to add
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If no path was specified
  
  IllegalArchivePathException - If the path is invalid.
- addAsDirectories
  
  T addAsDirectories(ArchivePath... paths) throws IllegalArgumentException
  
  Adds the specified directories.
  
  Parameters:
  
  paths - The paths to add
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If no paths were specified
  
  IllegalArchivePathException - If at least one path is invalid.
- addHandlers
  
  T addHandlers(ArchiveEventHandler... handlers)
  
  Adds an array of handlers for callback-based operations.
  
  Parameters:
  
  handlers - The handlers to be added for callback
  
  Returns:
  
  This archive
- get
  
  Node get(ArchivePath path) throws IllegalArgumentException
  
  Obtains the Node located at the specified path
  
  Parameters:
  
  path - The path to the node within the archive
  
  Returns:
  
  The Node, or null if nothing is found at the specified path
  
  Throws:
  
  IllegalArgumentException - If the path is not specified
- get
  
  Node get(String path) throws IllegalArgumentException
  
  Obtains the Node located at the specified path
  
  Parameters:
  
  path - The path to the node within the archive
  
  Returns:
  
  The Node, or null if nothing is found at the Path
  
  Throws:
  
  IllegalArgumentException - If the path is not specified
- getAsType
  <X extends Archive<X>> X getAsType(Class<X> type, String path)
  
  Get a nested Archive as a specific type.
  
  The found Archives must have been added as an Archive, no import is performed.
  
  Type Parameters:
  
  X - The type of archive
  
  Parameters:
  
  type - The Type to return the Archive as
  
  path - The location of the Archive
  
  Returns:
  
  The found Archive as given type or null if none found at given path
  
  Throws:
  
  IllegalArgumentException - if found Asset is not pointing to a Archive
  
  See Also:
  
  getAsType(Class, ArchivePath)
  
  add(Archive, ArchivePath, Class)
  
  add(Archive, String, Class)
- getAsType
  <X extends Archive<X>> X getAsType(Class<X> type, ArchivePath path)
  
  Get a nested Archive as a specific type.
  
  The found Archives must have been added as an Archive, no import is performed.
  
  Type Parameters:
  
  X - The type of archive
  
  Parameters:
  
  type - The Type to return the Archive as
  
  path - The location of the Archive
  
  Returns:
  
  The found Archive as given type or null if none found at given ArchivePath
  
  Throws:
  
  IllegalArgumentException - if found Asset is not pointing to a Archive
  
  See Also:
  
  add(Archive, ArchivePath, Class)
  
  add(Archive, String, Class)
- getAsType
  <X extends Archive<X>> Collection<X> getAsType(Class<X> type, Filter<ArchivePath> filter)
  
  Get all nested Archive matching the filter as a specific type.
  
  The found Archives must have been added as an Archive, no import is performed.
  
  Type Parameters:
  
  X - The type of archive
  
  Parameters:
  
  type - The Type to return the Archive as
  
  filter - Filter to match result
  
  Returns:
  
  A Collection of found Archives matching given filter or empty Collection if non found.
  
  Throws:
  
  IllegalArgumentException - if found Asset is not pointing to a Archive
  
  See Also:
  
  getAsType(Class, ArchivePath)
  
  add(Archive, ArchivePath, Class)
  
  add(Archive, String, Class)
- getAsType
  <X extends Archive<X>> X getAsType(Class<X> type, String path, ArchiveFormat archiveFormat)
  
  Get a nested Archive as a specific type using the specified ArchiveFormat
  
  Parameters:
  
  type - The Type to return the Archive as
  
  path - The location of the Archive
  
  archiveFormat - The archive format
  
  Returns:
  
  The found Archive as given type or null if none found at the given path
  
  See Also:
  
  add(Archive, ArchivePath, Class)
  
  add(Archive, String, Class)
- getAsType
  <X extends Archive<X>> X getAsType(Class<X> type, ArchivePath path, ArchiveFormat archiveFormat)
  
  Get a nested Archive located in a ArchivePath as a specific type using the specified ArchiveFormat
  
  Parameters:
  
  type - The Type to return the Archive as
  
  path - The location of the Archive
  
  archiveFormat - The archive format
  
  Returns:
  
  The found Archive as given type or null if none found at given ArchivePath
  
  See Also:
  
  add(Archive, ArchivePath, Class)
  
  add(Archive, String, Class)
- getAsType
  <X extends Archive<X>> Collection<X> getAsType(Class<X> type, Filter<ArchivePath> filter, ArchiveFormat archiveFormat)
  
  Get all nested Archive matching the filter as a specific type using the specified ArchiveFormat.
  
  Type Parameters:
  
  X - The type of archive
  
  Parameters:
  
  type - The Type to return the Archive as
  
  filter - Filter to match result
  
  archiveFormat - The archive format
  
  Returns:
  
  A Collection of found Archives matching given filter or empty Collection if non found.
  
  See Also:
  
  getAsType(Class, ArchivePath, ArchiveFormat)
  
  add(Archive, ArchivePath, Class)
  
  add(Archive, String, Class)
- contains
  
  boolean contains(ArchivePath path) throws IllegalArgumentException
  
  Denotes whether this archive contains a resource at the specified path
  
  Parameters:
  
  path - The path to the resource
  
  Returns:
  
  true if the archive contains the resource, false otherwise
  
  Throws:
  
  IllegalArgumentException - If the path is not specified
- contains
  
  boolean contains(String path) throws IllegalArgumentException
  
  Denotes whether this archive contains a resource at the specified path
  
  Parameters:
  
  path - The path to the resource
  
  Returns:
  
  true if the archive contains the resource, false otherwise
  
  Throws:
  
  IllegalArgumentException - If the path is not specified
- delete
  
  Node delete(ArchivePath path) throws IllegalArgumentException
  
  Removes the Node in the Archive at the specified ArchivePath. If the path is a directory, recursively removes all contents. If the path does not exist, return null.
  
  Parameters:
  
  path - The path to the node to be removed
  
  Returns:
  
  The Node removed
  
  Throws:
  
  IllegalArgumentException - If the path is not specified
- delete
  Node delete(String archivePath) throws IllegalArgumentException
  
  Removes the Node in the Archive at the ArchivePath indicated by the specified String archivePath. If the path is a directory, recursively removes all contents. If the path does not exist, return null.
  
  Parameters:
  
  archivePath - The path to the node to be removed
  
  Returns:
  
  The Node removed
  
  Throws:
  
  IllegalArgumentException - If the path is not specified
  
  See Also:
  
  delete(ArchivePath)
- getContent
  
  Map<ArchivePath, Node> getContent()
  
  Obtains all assets in this archive, along with their respective paths. The returned Map will be an immutable view.
  
  Returns:
  
  A map of all paths and nodes in the archive
- getContent
  
  Map<ArchivePath, Node> getContent(Filter<ArchivePath> filter)
  
  Obtains all assets matching given filter in this archive, along with its respective Path. The returned Map will be an immutable view.
  
  Parameters:
  
  filter - Filter to match assets
  
  Returns:
  
  A map of the paths and nodes found in the archive matching the filter
- filter
  T filter(Filter<ArchivePath> filter)
  
  Obtains all assets matching given filter in this archive as a new Archive.
  
  This is an alias for shallowCopy(Filter).
  
  Parameters:
  
  filter - Filter to match assets
  
  Returns:
  
  A new archive containing the filtered assets
  
  See Also:
  
  shallowCopy(Filter)
- add
  
  T add(Archive<?> archive, ArchivePath path, Class<? extends StreamExporter> exporter) throws IllegalArgumentException
  
  Add an archive under a specific context and maintain the archive name as context path.
  
  Parameters:
  
  archive - The archive to add
  
  path - The path to use
  
  exporter - Exporter type to use in fulfilling the Asset.openStream() contract for the added (nested) archive.
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If any argument is not specified
- add
  
  T add(Archive<?> archive, String path, Class<? extends StreamExporter> exporter) throws IllegalArgumentException
  
  Add an archive under a specific context and maintain the archive name as context path.
  
  Parameters:
  
  archive - The archive to add
  
  path - The path to use
  
  exporter - Exporter type to use in fulfilling the Asset.openStream() contract for the added (nested) archive.
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the path or archive are not specified
- merge
  
  T merge(Archive<?> source) throws IllegalArgumentException
  
  Merge the contents from an existing archive without maintaining the archive name in the context path.
  
  Parameters:
  
  source - Archive to add contents from
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the existing archive is not specified
- merge
  
  T merge(Archive<?> source, Filter<ArchivePath> filter) throws IllegalArgumentException
  
  Merge the contents from an existing archive without maintaining the archive name in the context path.
  The filter controls which ArchivePaths to include from the source Archive.
  
  Parameters:
  
  source - Archive to add contents from
  
  filter - Filter to match paths to be included
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the existing archive is not specified
- merge
  
  T merge(Archive<?> source, ArchivePath path) throws IllegalArgumentException
  
  Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path.
  
  Parameters:
  
  source - Archive to add contents from
  
  path - Path to add contents to
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the path or existing archive is not specified
- merge
  
  T merge(Archive<?> source, String path) throws IllegalArgumentException
  
  Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path.
  
  Parameters:
  
  source - Archive to add contents from
  
  path - Path to add contents to
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the path or existing archive is not specified
- merge
  
  T merge(Archive<?> source, ArchivePath path, Filter<ArchivePath> filter) throws IllegalArgumentException
  
  Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path. The filter controls which ArchivePaths to include from the source Archive.
  
  Parameters:
  
  source - Archive to add contents from
  
  path - Path to add contents to
  
  filter - Filter to match paths to be included
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the path or existing archive is not specified
- merge
  
  T merge(Archive<?> source, String path, Filter<ArchivePath> filter) throws IllegalArgumentException
  
  Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path. The filter controls which ArchivePaths to include from the source Archive.
  
  Parameters:
  
  source - Archive to add contents from
  
  path - Path to add contents to
  
  filter - Filter to match paths to be included
  
  Returns:
  
  This archive
  
  Throws:
  
  IllegalArgumentException - If the path or existing archive is not specified
- move
  
  T move(ArchivePath source, ArchivePath target) throws IllegalArgumentException, IllegalArchivePathException
  
  Moves the asset under the source path to the target path.
  
  Parameters:
  
  source - The context under which to remove the assets
  
  target - The context under which to add the moved assets
  
  Returns:
  
  the resulting archive with the moved assets
  
  Throws:
  
  IllegalArgumentException - If any of the paths is not specified
  
  IllegalArchivePathException - If the source path is invalid.
- move
  
  T move(String source, String target) throws IllegalArgumentException, IllegalArchivePathException
  
  Moves the asset under the source path to the target path.
  
  Parameters:
  
  source - The context under which to remove the assets
  
  target - The context under which to add the moved assets
  
  Returns:
  
  the resulting archive with the moved assets
  
  Throws:
  
  IllegalArgumentException - If any of the paths is not specified
  
  IllegalArchivePathException - If the source path is invalid.
- toString
  
  String toString()
  
  Acts as a shorthand for toString(Formatter) where the Formatters.SIMPLE is leveraged.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  A string representation of the archive using the simple formatter
- toString
  
  String toString(boolean verbose)
  
  If "true" is specified, acts as a shorthand for toString(Formatter) where the Formatters.VERBOSE is leveraged. Otherwise, the Formatters.SIMPLE will be used (equivalent to toString()).
  
  Parameters:
  
  verbose - If true, use the verbose formatter; otherwise use the simple formatter
  
  Returns:
  
  A string representation of the archive
- toString
  
  String toString(Formatter formatter) throws IllegalArgumentException
  
  Returns a view of this Archive as returned from the specified Formatter. Common options may be to use the predefined formatters located in Formatters
  
  Parameters:
  
  formatter - The formatter to use
  
  Returns:
  
  A string representation of the archive using the specified formatter
  
  Throws:
  
  IllegalArgumentException - If the formatter is not specified
- writeTo
  
  void writeTo(OutputStream outputStream, Formatter formatter) throws IllegalArgumentException
  
  Prints the content of this Archive to the specified OutputStream on the format defined by the specified Formatter. The caller is responsible for opening, flushing and eventually closing the stream.
  
  Parameters:
  
  outputStream - the stream to print the archive contents to
  
  formatter - the output format
  
  Throws:
  
  IllegalArgumentException - if an exceptions occur when writing the archive contents.
- shallowCopy
  
  Archive<T> shallowCopy()
  
  Creates a shallow copy of this Archive. Assets from this archive are made available under the same paths. However, removing old assets or adding new assets on this archive affects does not affect the new archive.
  
  Returns:
  
  a new archive with a copy of the pointers to the assets
- shallowCopy
  
  Archive<T> shallowCopy(Filter<ArchivePath> filter)
  
  Creates a shallow copy of this Archive based on given filter. Assets from this archive are made available under the same paths. However, removing old assets or adding new assets on this archive affects does not affect the new archive. This allows for filtering of both directory-based and Asset-based paths.
  
  Returns:
  
  a new archive with a copy of the pointers to the assets

Interface Archive<T extends Archive<T>>

Method Summary

Methods inherited from interface Assignable

Method Details

getName

getId

add

add

add

add

add

addAsDirectory

addAsDirectories

addAsDirectory

addAsDirectories

addHandlers

get

get

getAsType

getAsType

getAsType

getAsType

getAsType

getAsType

contains

contains

delete

delete

getContent

getContent

filter

add

add

merge

merge

merge

merge

merge

merge

move

move

toString

toString

toString

writeTo

shallowCopy

shallowCopy