org.jboss.shrinkwrap.api

Interface Archive<T extends Archive<T>>

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 and Description
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(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(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(Asset asset, String target) Adds the specified resource 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(NamedAsset namedAsset) Adds the asset encapsulated within the specified NamedAsset under the encapsulated name and target (directory)
T	addAsDirectories(ArchivePath... paths) Adds the specified directories.
T	addAsDirectories(String... paths) Adds the specified directories.
T	addAsDirectory(ArchivePath path) Adds the specified directory.
T	addAsDirectory(String path) Adds the specified directory.
T	addHandlers(ArchiveEventHandler... handlers) Add an array of listeners for call back based.
boolean	contains(ArchivePath path) Denotes whether this archive contains a resource at the specified path
boolean	contains(String path) Denotes whether this archive contains a resource at the specified path
Node	delete(ArchivePath path) Removes the Node in the Archive at the specified ArchivePath.
Node	delete(String archivePath) Removes the Node in the Archive at the ArchivePath indicated by the specified String 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(ArchivePath path) Obtains the Node located at the specified path
Node	get(String path) Obtains the Node located at the specified path
<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 a 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 specify 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 a 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 specify ArchiveFormat.
<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 a 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 specify 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 (ie.
T	merge(Archive<?> source) Merge the contents from an existing archive 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	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	move(ArchivePath source, ArchivePath target) Moves the asset under the source path to the target path.
T	move(String source, String 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.Assets from this archive are made available under the same paths.
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 org.jboss.shrinkwrap.api.Assignable

as

Method Detail

getName

String getName()

Obtains the name of this archive (ie. myLibrary.jar)

getId

String getId()

Obtains a globally-unique identifier for this Archive

Returns:

add

T add(Asset asset,
      ArchivePath target)
throws IllegalArgumentException

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

Parameters:

target - The context under which to add the assets

asset -

Returns:

Throws:

IllegalArgumentException - If no target or assets 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 be treating the specified path as a prefix namespace, then appending the name.

Parameters:

target - The context directory under which to add the asset

name - The name to assign the assent under the target namespace

asset -

Returns:

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 be treating the specified path as a prefix namespace, then appending the name.

Parameters:

target - The context directory under which to add the asset

name - The name to assign the assent under the target namespace

asset -

Returns:

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)

Parameters:

namedAsset -

Returns:

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 resource under the context denoted by the specified target

Parameters:

target -

asset -

Returns:

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)

Add an array of listeners for call back based.

Parameters:

listener - CallBack on add

Returns:

This archive

get

Node get(ArchivePath path)
  throws IllegalArgumentException

Obtains the Node located at the specified path

Parameters:

path -

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 -

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 a Archive, no import is performed.

Type Parameters:

X -

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 a Archive, no import is performed.

Type Parameters:

X -

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 a Archive, no import is performed.

Type Parameters:

X -

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 specify 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 specify 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 specify ArchiveFormat.

Type Parameters:

X -

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 -

Returns:

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 -

Returns:

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 -

Returns:

The Node removed

Throws:

IllegalArgumentException

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 -

Returns:

The Node removed

Throws:

IllegalArgumentException

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:

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.

Returns:

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 -

Returns:

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:

path - to use

archive - to add

exporter - Exporter type to use in fulfilling the Asset.openStream() contract for the added (nested) archive.

Returns:

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:

path - to use

archive - to add

exporter - Exporter type to use in fulfilling the Asset.openStream() contract for the added (nested) archive.

Returns:

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:

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 control which ArchivePaths to include form the source Archive.

Parameters:

source - Archive to add contents from

Returns:

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:

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:

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 control which ArchivePaths to include form the source Archive.

Parameters:

source - Archive to add contents from

path - Path to add contents to

filter - Filter to use for including Assets in the merge.

Returns:

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 control which ArchivePaths to include form the source Archive.

Parameters:

source - Archive to add contents from

path - Path to add contents to

filter - Filter to use for including Assets in the merge.

Returns:

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:

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()).

Returns:

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 -

Returns:

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.

Returns:

a new archive with a copy of the pointers to the assets