com.ibm.wsspi.artifact.overlay
Interface OverlayContainer

All Superinterfaces:
ArtifactContainer, EnclosedEntity, Entity, java.lang.Iterable<ArtifactEntry>

public interface OverlayContainer
extends ArtifactContainer

Version of overlay container with only support for adding/overriding of entries.

Overlay Container extends the Artifact API Container, making it useable whereever such Containers are used.
The aim is to allow a Container to be Wrapped with a layer that can..

Overlaid Entries may override Entry.convertToContainer, but if so the Overlay must not contain overlaid Entries for paths within Containers returned from such overrides.


Method Summary
 void addToNonPersistentCache(java.lang.String path, java.lang.Class owner, java.lang.Object data)
          Stores some data associated with the given container/entry path within non persistent in memory cache associated with this overlay instance.
 boolean addToOverlay(ArtifactEntry e)
          Adds an Entry to the Overlay.
 boolean addToOverlay(ArtifactEntry e, java.lang.String path, boolean representsNewRoot)
          Adds an Entry to the Overlay.
 ArtifactContainer getContainerBeingOverlaid()
          Get the Container this Overlay is wrapping
 java.lang.Object getFromNonPersistentCache(java.lang.String path, java.lang.Class owner)
          Obtains some data associated with the given container/entry path within non persistent in memory cache associated with this overlay instance.
 java.util.Set<java.lang.String> getMaskedPaths()
          Obtain the current set of masked paths.
 java.util.Set<java.lang.String> getOverlaidPaths()
          Obtains the set of paths within the OverlayContainer known to be overlaid.
 OverlayContainer getOverlayForEntryPath(java.lang.String path)
          Obtain the nested overlay stored for a given path.
 OverlayContainer getParentOverlay()
          Obtain the overlay container that holds this one.
 boolean isMasked(java.lang.String path)
          Query if a path is currently masked via 'mask'.
 boolean isOverlaid(java.lang.String path)
          Queries if a path is currently overlaid.
 void mask(java.lang.String path)
          Hides any Entry at the path supplied.
 void removeFromNonPersistentCache(java.lang.String path, java.lang.Class owner)
          Removes some data associated with the given container/entry path within non persistent in memory cache associated with this overlay instance.
 boolean removeFromOverlay(java.lang.String path)
          Removes any overlay for a given path.
 void setOverlayDirectory(java.io.File cacheDirForOverlayContent, java.io.File f)
          Set the location this overlay should use to obtain & store data to.
 void unMask(java.lang.String path)
          UnHides an Entry previously hidden via 'mask'.
 
Methods inherited from interface com.ibm.wsspi.artifact.ArtifactContainer
getArtifactNotifier, getEntry, getEntryInEnclosingContainer, getURLs, isRoot, stopUsingFastMode, useFastMode
 
Methods inherited from interface java.lang.Iterable
iterator
 
Methods inherited from interface com.ibm.wsspi.artifact.EnclosedEntity
getEnclosingContainer, getPath, getPhysicalPath, getRoot
 
Methods inherited from interface com.ibm.wsspi.artifact.Entity
getName
 

Method Detail

setOverlayDirectory

void setOverlayDirectory(java.io.File cacheDirForOverlayContent,
                         java.io.File f)
Set the location this overlay should use to obtain & store data to.

f must exist, must be a directory, and must be writable.

Until this method is called, addEntry is non functional on this overlay.

Parameters:
cacheDirForOverlayContent - location to hold extracted nested overlaid archives if any.
f - Directory to hold overlay data.
Throws:
java.lang.IllegalStateException - if the directory has already been set
java.lang.IllegalArgumentException - if f does not exist/is not a directory

getContainerBeingOverlaid

ArtifactContainer getContainerBeingOverlaid()
Get the Container this Overlay is wrapping

Intended to allow access to original data, to avoid users creating the 'remove, read data, add new overlay based on orig data' pattern.


mask

void mask(java.lang.String path)
Hides any Entry at the path supplied.

Applies to both overlaid, and original Entries.
Applies even if Entry is added via overlay after mask invocation.

Parameters:
path - The path to hide.

unMask

void unMask(java.lang.String path)
UnHides an Entry previously hidden via 'mask'.
Has no effect if path is not masked.

Parameters:
path - The path to unhide.

isMasked

boolean isMasked(java.lang.String path)
Query if a path is currently masked via 'mask'.

Parameters:
path - The path to query.
Returns:
true if masked, false otherwise.

getMaskedPaths

java.util.Set<java.lang.String> getMaskedPaths()
Obtain the current set of masked paths.

Returns:
Set of Strings comprising the current mask entries.

addToOverlay

boolean addToOverlay(ArtifactEntry e)
Adds an Entry to the Overlay.

Entry is added at Entry.getPath(), Entry/path need not already exist within the Container
User must ensure that Entry remains usable. (Eg underlying artifacts are not closed, removed etc)

If the Entry is convertible to Container, behavior is undefined if attempts are made to overlay the contained paths via this method.

Parameters:
e - the Entry to Add.
Returns:
true if the entry was added successfully, false otherwise.

addToOverlay

boolean addToOverlay(ArtifactEntry e,
                     java.lang.String path,
                     boolean representsNewRoot)
Adds an Entry to the Overlay.

Entry is added at path Entry/path need not already exist within the Container
User must ensure that Entry remains usable. (Eg underlying artifacts are not closed, removed etc)

If the Entry is convertible to Container, behavior is undefined if attempts are made to overlay the contained paths via this method.

Parameters:
e - the Entry to Add.
path - the Location to add the Entry at within the Overlay (Entry.getPath is ignored).
representsNewRoot - if e can convertToContainer, should that container be treated as isRoot true? (Entry.convertToContainer.isRoot is ignored).
Returns:
true if the entry was added successfully, false otherwise.

removeFromOverlay

boolean removeFromOverlay(java.lang.String path)
Removes any overlay for a given path.

Parameters:
path - The path to stop overlaying.

isOverlaid

boolean isOverlaid(java.lang.String path)
Queries if a path is currently overlaid.

Note this will only query the paths added via addToOverlay, if Entries added via addToOverlay can convert to containers, paths within will NOT be reported

Parameters:
path - The path to query
Returns:
true if the path has an overlay registered. False otherwise.

getOverlaidPaths

java.util.Set<java.lang.String> getOverlaidPaths()
Obtains the set of paths within the OverlayContainer known to be overlaid.

Returns:
The set of paths within the OverlayContainer known to be overlaid.

getOverlayForEntryPath

OverlayContainer getOverlayForEntryPath(java.lang.String path)
Obtain the nested overlay stored for a given path.

Overlays apply within a given Root of an ArtifactContainer only, if you navigate to a container where isRoot=true, then it is a new Overlay, and if you wish to override content in it, you must obtain it via this method.

This method will return null if the path does not represent an ArtifactEntry where isRoot=true, within the current overlay.

Parameters:
path - Path to obtain Overlay for nested root.
Returns:
Overlay if one is available, null otherwise.

getParentOverlay

OverlayContainer getParentOverlay()
Obtain the overlay container that holds this one.

May return null if this overlay container overlays the top most root.

Returns:
the OverlayContainer that holds this OverlayContainer, or null if there is none.

addToNonPersistentCache

void addToNonPersistentCache(java.lang.String path,
                             java.lang.Class owner,
                             java.lang.Object data)
Stores some data associated with the given container/entry path within non persistent in memory cache associated with this overlay instance.

Parameters:
path - Path to associate data with.
owner - Class of caller setting data, allows multiple adapters to cache against a given path.
data - Data to store for caller.

removeFromNonPersistentCache

void removeFromNonPersistentCache(java.lang.String path,
                                  java.lang.Class owner)
Removes some data associated with the given container/entry path within non persistent in memory cache associated with this overlay instance.

Parameters:
path - Path to associate data with.
owner - Class of caller setting data, allows multiple adapters to cache against a given path.

getFromNonPersistentCache

java.lang.Object getFromNonPersistentCache(java.lang.String path,
                                           java.lang.Class owner)
Obtains some data associated with the given container/entry path within non persistent in memory cache associated with this overlay instance.

Parameters:
path - Path associated with data.
owner - Class of caller getting data, allows multiple adapters to cache against a given path.