Package org.jboss.shrinkwrap.api
Interface Archive<T extends Archive<T>>
-
- All Superinterfaces:
Assignable
- All Known Subinterfaces:
EnterpriseArchive
,GenericArchive
,JavaArchive
,MemoryMapArchive
,ResourceAdapterArchive
,WebArchive
- All Known Implementing Classes:
ArchiveBase
,ContainerBase
,EnterpriseArchiveImpl
,EnterpriseContainerBase
,GenericArchiveImpl
,JavaArchiveImpl
,MemoryMapArchiveBase
,MemoryMapArchiveImpl
,ResourceAdapterArchiveImpl
,ResourceAdapterContainerBase
,WebArchiveImpl
,WebContainerBase
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.
AllArchive
types support the addition ofNode
s under a designatedArchivePath
(context). The contents of aNode
are either a directory orAsset
.
Archive
s are generally created via anArchiveFactory
or via the default configuration shortcutShrinkWrap
utility class.
BecauseArchive
s areAssignable
, 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: $
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description T
add(Archive<?> archive, java.lang.String path, java.lang.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, java.lang.Class<? extends StreamExporter> exporter)
Add an archive under a specific context and maintain the archive name as context path.T
add(Asset asset, java.lang.String target)
Adds the specified resource under the context denoted by the specified targetT
add(Asset asset, java.lang.String target, java.lang.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 contextT
add(Asset asset, ArchivePath target, java.lang.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 specifiedNamedAsset
under the encapsulated name and target (directory)T
addAsDirectories(java.lang.String... paths)
Adds the specified directories.T
addAsDirectories(ArchivePath... paths)
Adds the specified directories.T
addAsDirectory(java.lang.String path)
Adds the specified directory.T
addAsDirectory(ArchivePath path)
Adds the specified directory.T
addHandlers(ArchiveEventHandler... handlers)
Add an array of listeners for call back based.boolean
contains(java.lang.String path)
Denotes whether this archive contains a resource at the specified pathboolean
contains(ArchivePath path)
Denotes whether this archive contains a resource at the specified pathNode
delete(java.lang.String archivePath)
Node
delete(ArchivePath path)
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(java.lang.String path)
Obtains theNode
located at the specified pathNode
get(ArchivePath path)
Obtains theNode
located at the specified path<X extends Archive<X>>
XgetAsType(java.lang.Class<X> type, java.lang.String path)
Get a nestedArchive
as a specific type.
The found Archives must have been added as a Archive, no import is performed.<X extends Archive<X>>
XgetAsType(java.lang.Class<X> type, java.lang.String path, ArchiveFormat archiveFormat)
Get a nestedArchive
as a specific type using the specifyArchiveFormat
<X extends Archive<X>>
XgetAsType(java.lang.Class<X> type, ArchivePath path)
Get a nestedArchive
as a specific type.
The found Archives must have been added as a Archive, no import is performed.<X extends Archive<X>>
XgetAsType(java.lang.Class<X> type, ArchivePath path, ArchiveFormat archiveFormat)
<X extends Archive<X>>
java.util.Collection<X>getAsType(java.lang.Class<X> type, Filter<ArchivePath> filter)
Get all nestedArchive
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>>
java.util.Collection<X>getAsType(java.lang.Class<X> type, Filter<ArchivePath> filter, ArchiveFormat archiveFormat)
Get all nestedArchive
matching the filter as a specific type using the specifyArchiveFormat
.java.util.Map<ArchivePath,Node>
getContent()
Obtains all assets in this archive, along with their respective paths.java.util.Map<ArchivePath,Node>
getContent(Filter<ArchivePath> filter)
Obtains all assets matching given filter in this archive, along with its respective Path.java.lang.String
getId()
Obtains a globally-unique identifier for thisArchive
java.lang.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, java.lang.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, java.lang.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(java.lang.String source, java.lang.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 thisArchive
.Archive<T>
shallowCopy(Filter<ArchivePath> filter)
Creates a shallow copy of thisArchive
based on given filter.Assets from this archive are made available under the same paths.java.lang.String
toString()
Acts as a shorthand fortoString(Formatter)
where theFormatters.SIMPLE
is leveraged.java.lang.String
toString(boolean verbose)
If "true" is specified, acts as a shorthand fortoString(Formatter)
where theFormatters.VERBOSE
is leveraged.java.lang.String
toString(Formatter formatter)
void
writeTo(java.io.OutputStream outputStream, Formatter formatter)
-
Methods inherited from interface org.jboss.shrinkwrap.api.Assignable
as
-
-
-
-
Method Detail
-
getName
java.lang.String getName()
Obtains the name of this archive (ie. myLibrary.jar)
-
getId
java.lang.String getId()
Obtains a globally-unique identifier for thisArchive
- Returns:
-
add
T add(Asset asset, ArchivePath target) throws java.lang.IllegalArgumentException
Adds the specified asset under the specified path into the target context- Parameters:
target
- The context under which to add the assetsasset
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If no target or assets were specifiedIllegalArchivePathException
- If the target is invalid.
-
add
T add(Asset asset, ArchivePath target, java.lang.String name) throws java.lang.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 assetname
- The name to assign the assent under the target namespaceasset
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the target, name, or asset was not specifiedIllegalArchivePathException
- If the target is invalid.
-
add
T add(Asset asset, java.lang.String target, java.lang.String name) throws java.lang.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 assetname
- The name to assign the assent under the target namespaceasset
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the target, name, or asset was not specifiedIllegalArchivePathException
- If the target is invalid.
-
add
T add(NamedAsset namedAsset) throws java.lang.IllegalArgumentException
Adds the asset encapsulated within the specifiedNamedAsset
under the encapsulated name and target (directory)- Parameters:
namedAsset
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If either the target or asset is not specifiedIllegalArchivePathException
- If the target is invalid.
-
add
T add(Asset asset, java.lang.String target) throws java.lang.IllegalArgumentException
Adds the specified resource under the context denoted by the specified target- Parameters:
target
-asset
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If either the target or asset is not specifiedIllegalArchivePathException
- If the target is invalid.
-
addAsDirectory
T addAsDirectory(java.lang.String path) throws java.lang.IllegalArgumentException
Adds the specified directory.- Parameters:
path
- The path to add- Returns:
- This archive
- Throws:
java.lang.IllegalArgumentException
- If no path was specifiedIllegalArchivePathException
- If the path is invalid.
-
addAsDirectories
T addAsDirectories(java.lang.String... paths) throws java.lang.IllegalArgumentException
Adds the specified directories.- Parameters:
paths
- The paths to add- Returns:
- This archive
- Throws:
java.lang.IllegalArgumentException
- If no paths were specifiedIllegalArchivePathException
- If at least one path is invalid.
-
addAsDirectory
T addAsDirectory(ArchivePath path) throws java.lang.IllegalArgumentException
Adds the specified directory.- Parameters:
path
- The path to add- Returns:
- This archive
- Throws:
java.lang.IllegalArgumentException
- If no path was specifiedIllegalArchivePathException
- If the path is invalid.
-
addAsDirectories
T addAsDirectories(ArchivePath... paths) throws java.lang.IllegalArgumentException
Adds the specified directories.- Parameters:
paths
- The paths to add- Returns:
- This archive
- Throws:
java.lang.IllegalArgumentException
- If no paths were specifiedIllegalArchivePathException
- 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 java.lang.IllegalArgumentException
Obtains theNode
located at the specified path- Parameters:
path
-- Returns:
- The
Node
, or null if nothing is found at the specified path - Throws:
java.lang.IllegalArgumentException
- If the path is not specified
-
get
Node get(java.lang.String path) throws java.lang.IllegalArgumentException
Obtains theNode
located at the specified path- Parameters:
path
-- Returns:
- The
Node
, or null if nothing is found at the Path - Throws:
java.lang.IllegalArgumentException
- If the path is not specified
-
getAsType
<X extends Archive<X>> X getAsType(java.lang.Class<X> type, java.lang.String path)
Get a nestedArchive
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 aspath
- The location of the Archive- Returns:
- The found Archive as given type or null if none found at given path
- Throws:
java.lang.IllegalArgumentException
- if foundAsset
is not pointing to aArchive
- See Also:
getAsType(Class, ArchivePath)
,add(Archive, ArchivePath, Class)
,add(Archive, String, Class)
-
getAsType
<X extends Archive<X>> X getAsType(java.lang.Class<X> type, ArchivePath path)
Get a nestedArchive
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 aspath
- The location of the Archive- Returns:
- The found Archive as given type or null if none found at given
ArchivePath
- Throws:
java.lang.IllegalArgumentException
- if foundAsset
is not pointing to aArchive
- See Also:
add(Archive, ArchivePath, Class)
,add(Archive, String, Class)
-
getAsType
<X extends Archive<X>> java.util.Collection<X> getAsType(java.lang.Class<X> type, Filter<ArchivePath> filter)
Get all nestedArchive
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 asfilter
- Filter to match result- Returns:
- A
Collection
of found Archives matching given filter or emptyCollection
if non found. - Throws:
java.lang.IllegalArgumentException
- if foundAsset
is not pointing to aArchive
- See Also:
getAsType(Class, ArchivePath)
,add(Archive, ArchivePath, Class)
,add(Archive, String, Class)
-
getAsType
<X extends Archive<X>> X getAsType(java.lang.Class<X> type, java.lang.String path, ArchiveFormat archiveFormat)
Get a nestedArchive
as a specific type using the specifyArchiveFormat
- Parameters:
type
- The Type to return the Archive aspath
- The location of the ArchivearchiveFormat
- 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(java.lang.Class<X> type, ArchivePath path, ArchiveFormat archiveFormat)
- Parameters:
type
- The Type to return the Archive aspath
- The location of the ArchivearchiveFormat
- 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>> java.util.Collection<X> getAsType(java.lang.Class<X> type, Filter<ArchivePath> filter, ArchiveFormat archiveFormat)
Get all nestedArchive
matching the filter as a specific type using the specifyArchiveFormat
.- Type Parameters:
X
-- Parameters:
type
- The Type to return the Archive asfilter
- Filter to match resultarchiveFormat
- The archive format- Returns:
- A
Collection
of found Archives matching given filter or emptyCollection
if non found. - See Also:
getAsType(Class, ArchivePath, ArchiveFormat)
,add(Archive, ArchivePath, Class)
,add(Archive, String, Class)
-
contains
boolean contains(ArchivePath path) throws java.lang.IllegalArgumentException
Denotes whether this archive contains a resource at the specified path- Parameters:
path
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the path is not specified
-
contains
boolean contains(java.lang.String path) throws java.lang.IllegalArgumentException
Denotes whether this archive contains a resource at the specified path- Parameters:
path
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the path is not specified
-
delete
Node delete(ArchivePath path) throws java.lang.IllegalArgumentException
Removes theNode
in theArchive
at the specifiedArchivePath
. 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:
java.lang.IllegalArgumentException
-
delete
Node delete(java.lang.String archivePath) throws java.lang.IllegalArgumentException
Removes theNode
in theArchive
at theArchivePath
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:
java.lang.IllegalArgumentException
- See Also:
delete(ArchivePath)
-
getContent
java.util.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
java.util.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, java.lang.Class<? extends StreamExporter> exporter) throws java.lang.IllegalArgumentException
Add an archive under a specific context and maintain the archive name as context path.- Parameters:
path
- to usearchive
- to addexporter
- Exporter type to use in fulfilling theAsset.openStream()
contract for the added (nested) archive.- Returns:
- Throws:
java.lang.IllegalArgumentException
- If any argument is not specified
-
add
T add(Archive<?> archive, java.lang.String path, java.lang.Class<? extends StreamExporter> exporter) throws java.lang.IllegalArgumentException
Add an archive under a specific context and maintain the archive name as context path.- Parameters:
path
- to usearchive
- to addexporter
- Exporter type to use in fulfilling theAsset.openStream()
contract for the added (nested) archive.- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the path or archive are not specified
-
merge
T merge(Archive<?> source) throws java.lang.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:
java.lang.IllegalArgumentException
- If the existing archive is not specified
-
merge
T merge(Archive<?> source, Filter<ArchivePath> filter) throws java.lang.IllegalArgumentException
Merge the contents from an existing archive without maintaining the archive name in the context path. The filter control whichArchivePath
s to include form the sourceArchive
.- Parameters:
source
- Archive to add contents from- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the existing archive is not specified
-
merge
T merge(Archive<?> source, ArchivePath path) throws java.lang.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 frompath
- Path to add contents to- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the path or existing archive is not specified
-
merge
T merge(Archive<?> source, java.lang.String path) throws java.lang.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 frompath
- Path to add contents to- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the path or existing archive is not specified
-
merge
T merge(Archive<?> source, ArchivePath path, Filter<ArchivePath> filter) throws java.lang.IllegalArgumentException
Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path. The filter control whichArchivePath
s to include form the sourceArchive
.- Parameters:
source
- Archive to add contents frompath
- Path to add contents tofilter
- Filter to use for includingAsset
s in the merge.- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the path or existing archive is not specified
-
merge
T merge(Archive<?> source, java.lang.String path, Filter<ArchivePath> filter) throws java.lang.IllegalArgumentException
Merge the contents from an existing archive in a specific path without maintaining the archive name in the context path. The filter control whichArchivePath
s to include form the sourceArchive
.- Parameters:
source
- Archive to add contents frompath
- Path to add contents tofilter
- Filter to use for includingAsset
s in the merge.- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the path or existing archive is not specified
-
move
T move(ArchivePath source, ArchivePath target) throws java.lang.IllegalArgumentException, IllegalArchivePathException
Moves the asset under the source path to the target path.- Parameters:
source
- The context under which to remove the assetstarget
- The context under which to add the moved assets- Returns:
- the resulting archive with the moved assets
- Throws:
java.lang.IllegalArgumentException
- If any of the paths is not specifiedIllegalArchivePathException
- If the source path is invalid.
-
move
T move(java.lang.String source, java.lang.String target) throws java.lang.IllegalArgumentException, IllegalArchivePathException
Moves the asset under the source path to the target path.- Parameters:
source
- The context under which to remove the assetstarget
- The context under which to add the moved assets- Returns:
- the resulting archive with the moved assets
- Throws:
java.lang.IllegalArgumentException
- If any of the paths is not specifiedIllegalArchivePathException
- If the source path is invalid.
-
toString
java.lang.String toString()
Acts as a shorthand fortoString(Formatter)
where theFormatters.SIMPLE
is leveraged.- Overrides:
toString
in classjava.lang.Object
- Returns:
-
toString
java.lang.String toString(boolean verbose)
If "true" is specified, acts as a shorthand fortoString(Formatter)
where theFormatters.VERBOSE
is leveraged. Otherwise theFormatters.SIMPLE
will be used (equivalent totoString()
).- Returns:
-
toString
java.lang.String toString(Formatter formatter) throws java.lang.IllegalArgumentException
Returns a view of thisArchive
as returned from the specifiedFormatter
. Common options may be to use the predefined formatters located inFormatters
- Parameters:
formatter
-- Returns:
- Throws:
java.lang.IllegalArgumentException
- If the formatter is not specified
-
writeTo
void writeTo(java.io.OutputStream outputStream, Formatter formatter) throws java.lang.IllegalArgumentException
Prints the content of thisArchive
to the specifiedOutputStream
on the format defined by the specifiedFormatter
. The caller is responsible for opening, flushing and eventually closing the stream.- Parameters:
outputStream
- the stream to print the archive contents toformatter
- the output format- Throws:
java.lang.IllegalArgumentException
- if an exceptions occur when writing the archive contents.
-
shallowCopy
Archive<T> shallowCopy()
Creates a shallow copy of thisArchive
. 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 thisArchive
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
-
-