Package com.ibm.wsspi.artifact.overlay

Interface OverlayContainer

All Superinterfaces:
ArtifactContainer, EnclosedEntity, Entity, 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..

  • Mask & UnMask Entries that may be contained inside. A Masked path does not have to exist already, and if Masked, will also hide overlaid entries. Masked Paths can be dirs, entries, subdirs, etc.
  • Overlay an Entry, or UnOverlay an Entry. Overlaid Entries will return the supplied Entry instead of looking in the wrapped Container for it. UnOverlaying an entry will restore access to the original Entry in the wrapped container.

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 Details

    • setOverlayDirectory

      void setOverlayDirectory(File cacheDirForOverlayContent, 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:
      IllegalStateException - if the directory has already been set
      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(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(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(String path)
      Query if a path is currently masked via 'mask'.
      Parameters:
      path - The path to query.
      Returns:
      true if masked, false otherwise.

    • getMaskedPaths

      Set<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, 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(String path)
      Removes any overlay for a given path.

      Parameters:
      path - The path to stop overlaying.

    • isOverlaid

      boolean isOverlaid(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

      Set<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(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(String path, Class owner, 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(String path, 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

      Object getFromNonPersistentCache(String path, 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.