Package com.ibm.wsspi.kernel.service.location

Interface WsResource

public interface WsResource
This interface provides a wrapper/proxy for resources located by the WsLocationAdmin service. The nature of the underlying resource (local vs. remote, retrieved w/ http or some other service, etc.) should remain opaque to the caller.

A resource can be a WsResource.Type.FILE (e.g. a file), a WsResource.Type.DIRECTORY (e.g. a directory or folder), or a Type#URL (e.g., an HTTP resource.) A file can contain data, but not other files or files; a directory can contain other files or files, but no data.

Note that toExternalURI returns a URI, which is subject to URI encoding rules.

An WsResource instance is not synchronized against concurrent access, and offers no guarantees about potential conflicts when modifying the underlying resource.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    WsResource.Type
     

  • Method Summary

    Modifier and Type
    Method
    Description
    File
    asFile()
    Returns the file backing this wrapped resource.
    boolean
    create()
    Creates a resource if it does not exist.
    boolean
    delete()
    Deletes the wrapped/proxied resource.
    boolean
    exists()
    Tests whether the wrapped/proxied resource exists.
    InputStream
    get()
    Creates and returns an InputStream for reading the contents of the wrapped/proxied resource.
    ReadableByteChannel
    getChannel()
    Creates and returns a ReadableByteChannel for reading the contents of the wrapped/proxied resource.
    WsResource
    getChild(String name)
    Obtain an WsResource for the named child (direct descendant of this resource).
    Iterator<String>
    getChildren()
    Returns an Iterator that will iterate over the names of each of the children of this directory.
    Iterator<String>
    getChildren(String resourceRegex)
    Find the children whose names match the provided regular expression.
    long
    getLastModified()
    Returns the time that the wrapped/proxied resource was last modified.
    String
    getName()
    Returns the name of this resource.
    WsResource
    getParent()
    Obtain an WsResource for the parent of this resource.
    WsResource.Type
    getType()
    Return the resource type
    boolean
    isType(WsResource.Type resourceType)
    Tests whether the wrapped/proxied resource is of the specified type: WsResource.Type.
    long
    length()
    Returns the length of the wrapped/proxied resource.
    boolean
    moveTo(WsResource target)
    Moves this resource to the target resource.
    void
    put(InputStream source)
    Create or replace the content of this resource with the contents of the provided InputStream.
    void
    put(ReadableByteChannel source)
    Create or replace the content of this resource with the contents of the provided ReadableByteChannel.
    WritableByteChannel
    putChannel()
    Creates and returns a WritableByteChannel which can be used to replace the contents of the named resource.
    OutputStream
    putStream()
    Creates and returns an OutputStream which can be used to replace the contents of the named resource.
    WsResource
    resolveRelative(String relativeResourceURI)
    Resolve an WsResource relative to the current resource/location.
    boolean
    setLastModified(long lastModified)
    Set the time that the wrapped/proxied resource was last modified.
    URI
    toExternalURI()
    Constructs a URI that represents this wrapped resource.
    String
    toRepositoryPath()
    Constructs a String that represents this wrapped resource using symbolic roots.

  • Method Details

    • create

      boolean create()
      Creates a resource if it does not exist. The type of resource created depends on how the resource was resolved: a resource with a URI or repository path ending in a '/' will be created as a directory; a resource with a URI/path not ending in '/' will be created as a file.

      If the resource is a file, (put(InputStream), put(ReadableByteChannel), putChannel(), or putStream() can then be used to write to the new resource.

      If the resource is a directory, child files or files can be created by resolving the child location and calling create.

      Returns:
      true if and only if the wrapped/proxied resource is successfully created; false otherwise.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies access to create the file (in the case of a file/directory-backed resource)

    • delete

      boolean delete()
      Deletes the wrapped/proxied resource. If this resource is a directory (e.g. a directory), then it must be empty (no sub-files or files) in order to be deleted.
      Returns:
      true if and only if the wrapped/proxied resource is successfully deleted; false otherwise
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkDelete(java.lang.String) method denies delete access to the file (in the case of a file/directory-backed resource)

    • exists

      boolean exists()
      Tests whether the wrapped/proxied resource exists.
      Returns:
      true if and only if the wrapped resource exists; false otherwise
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file or directory (in the case of a file/directory-backed resource)

    • get

      InputStream get() throws IOException
      Creates and returns an InputStream for reading the contents of the wrapped/proxied resource.

      The caller is responsible for closing the returned input stream.

      Returns:
      An input stream for reading from the wrapped/proxied resource.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file (in the case of a file/directory-backed resource)
      IOException - If an I/O error occurs: if the resource has not been resolved, does not exist, is a directory rather than a file, or for some other reason cannot be opened for reading.

    • getChannel

      ReadableByteChannel getChannel() throws IOException
      Creates and returns a ReadableByteChannel for reading the contents of the wrapped/proxied resource.

      The caller is responsible for closing the returned nio channel.

      Returns:
      An input stream for reading from the wrapped/proxied resource.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file (in the case of a file/directory-backed resource).
      IOException - If an I/O error occurs: if the resource has not been resolved, does not exist, is a directory rather than a file, or for some other reason cannot be opened for reading.

    • getChild

      WsResource getChild(String name)
      Obtain an WsResource for the named child (direct descendant of this resource).

      Note that this method returns null when the child does not exist. This differs from resolve(String) which never returns null.

      Parameters:
      name - Name of child; can not contain path separator characters
      Returns:
      An WsResource for the child if this is a directory and the child exists. Returns null if the child name is null, if this resource is not a directory, if the child does not exist, or if an I/O error occurs.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the directory (in the case of a file/directory-backed resource).
      MalformedLocationException - if name contains path separators.
      IllegalArgumentException - if the child resource exists as a different type: i.e. if child name indicates the resource should be a directory and the resource exists as a file, or vice versa.

    • getChildren

      Iterator<String> getChildren()
      Returns an Iterator that will iterate over the names of each of the children of this directory.

      There is no guarantee that the names returned by the iterator will be in any specific order.

      Not thread safe.

      Returns:
      An Iterator that will iterate over a collection of Strings representing the children of this WsResource; the Iterator will have no elements if the directory is empty, if this resource is not a directory, or if an I/O error occurs.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the directory (in the case of a directory-backed resource)

    • getChildren

      Iterator<String> getChildren(String resourceRegex)
      Find the children whose names match the provided regular expression.

      The iterator will present the matching names in the order they were matched. If no resources were found, the iterator will have no elements.

      Parameters:
      regex - Regular expression used to filter the names of children.
      Returns:
      Iterator for the set/list of children whose names match the provided regular expression; the Iterator will have no elements if the directory is empty, if this resource is not a directory, or if an I/O error occurs.
      See Also:

    • getLastModified

      long getLastModified()
      Returns the time that the wrapped/proxied resource was last modified.
      Returns:
      A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or 0L if the file does not exist or if an I/O error occurs
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file (in the case of a file/directory-backed resource)

    • getName

      String getName()
      Returns the name of this resource.
      Returns:
      The name of the file or directory denoted by this abstract pathname. Node names will be terminated with a '/'.

    • getParent

      WsResource getParent()
      Obtain an WsResource for the parent of this resource.
      Returns:
      An WsResource for the parent, which will be a directory; returns null if this resource has not been resolved, or if the parent of the resource is not reachable.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the parent (in the case of a file/directory-backed resource)
      IllegalArgumentException - if parent resource already exists as a file.

    • getType

      WsResource.Type getType()
      Return the resource type
      Returns:
      type of WsResource.
      See Also:

    • isType

      boolean isType(WsResource.Type resourceType)
      Tests whether the wrapped/proxied resource is of the specified type: WsResource.Type. The resource must exist for its type to be determined.
      Returns:
      true if and only if the wrapped/proxied resource exists and matches the specified type; false otherwise.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

    • length

      long length()
      Returns the length of the wrapped/proxied resource. The return value is unspecified if this is not a file.
      Returns:
      the length, in bytes, of the file denoted by this wrapped/proxied resource, or 0L if not a file.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

    • moveTo

      boolean moveTo(WsResource target) throws IOException
      Moves this resource to the target resource. The (non-null) target resource must not exist before calling this method, it (and any missing parent files) will be created when the resource is moved.

      This should be viewed as a rename function: this resource (the source) is immutable. After calling this method (assuming it completes without an exception), exists() should return false.

      Parameters:
      target - The resolved WsResource that this resource should be moved to.
      Returns:
      true if and only if the renaming succeeded; false otherwise
      Throws:
      IOException - If the source resource (this) does not exist, if the source and target resources are not the same type (directory vs. file), if the target resource already exists or can not be created, or if there is any other error associated with moving the resource.
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to either the old or new pathnames
      NullPointerException - If parameter target is null

    • put

      void put(InputStream source) throws IOException
      Create or replace the content of this resource with the contents of the provided InputStream.

      If this resource is a file, this will also create any required parent files (e.g. calling getParent().mkdirs() on a File-backed resource).

      An output stream will be created, filled with the contents of the input stream, and closed. The caller should close the input stream.

      Parameters:
      source - InputStream containing the new contents of the resource. Method will return with no action if the source is null or empty.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to the file (in the case of a file-backed resource)
      IOException - If an I/O error occurs: if the resource does not exist and cannot be created, exists but is a directory rather than a file, or for some other reason cannot be opened for writing.

    • put

      void put(ReadableByteChannel source) throws IOException
      Create or replace the content of this resource with the contents of the provided ReadableByteChannel.

      If this resource is a file, this will also create any required parent files (e.g. calling getParent().mkdirs() on a File-backed resource).

      An output stream/writable channel will be created, filled with the contents from the source channel, and closed. The caller should close the provided source.

      Parameters:
      source - NIO ReadableByteChannel containing the new contents of the resource. Method will return with no action if the source is null or empty.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to the file (in the case of a file-backed resource)
      IOException - If an I/O error occurs: if the resource does not exist and cannot be created, exists but is a directory rather than a file, or for some other reason cannot be opened for writing.
      See Also:

    • putStream

      OutputStream putStream() throws IOException
      Creates and returns an OutputStream which can be used to replace the contents of the named resource. The returned stream will be for writing only, and will be a strict overwrite (not append).

      If this resource is a file, this will also create any required parent files (e.g. calling getParent().mkdirs() on a File-backed resource).

      The caller is responsible for closing the OutputStream.

      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to the file (in the case of a file-backed resource)
      IOException - If an I/O error occurs: if the resource does not exist and cannot be created, exists but is a directory rather than a file, or for some other reason cannot be opened for writing.

    • putChannel

      WritableByteChannel putChannel() throws IOException
      Creates and returns a WritableByteChannel which can be used to replace the contents of the named resource. The returned channel will be for writing only, and will be a strict overwrite (not append).

      If this resource is a file, this will also create any required parent files (e.g. calling getParent().mkdirs() on a File-backed resource).

      The caller is responsible for closing the channel.

      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to the file (in the case of a file-backed resource)
      IOException - If an I/O error occurs: if the resource does not exist and cannot be created, exists but is a directory rather than a file, or for some other reason cannot be opened for writing.

    • resolveRelative

      WsResource resolveRelative(String relativeResourceURI)
      Resolve an WsResource relative to the current resource/location.
      • If the current resource is a directory, an unqualified resource name will be resolved as a child of the directory, e.g. if this resource is "a/b/c/", and you resolve "d", the returned resource will be "a/b/c/d"
      • If the current resource is a file, an unqualified resource name will be resolved as a peer, e.g. if this resource is "a/b/c", and you resolve "d", the returned resource will be "a/b/d"
      • The special location "${/}" WsLocationConstants.SYMBOL_ROOT_NODE can be used to resolve this resource's root directory.
      Parameters:
      relativeResourceURI - String describing the artifact to resolve. Be sure to include the terminator when resolving a directory.
      Returns:
      new WsResource for the relative resource, or null if the provided string is null or not a valid relative URI, or if the relative location can not be determined (i.e. no associated root).
      Throws:
      MalformedLocationException - if relativeResourceURI is badly formed (contains illegal characters, etc.)
      IllegalArgumentException - if resource to be created already exists as a different type: i.e. if the resource uri indicates the resource should be a directory and the resource exists as a file, or vice versa; or if the relative path refers to a resource that is outside of the given file hierarchy (above the resource root).
      See Also:

    • setLastModified

      boolean setLastModified(long lastModified)
      Set the time that the wrapped/proxied resource was last modified.
      Parameters:
      lastModified - A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or 0L if the file does not exist or if an I/O error occurs
      Returns:
      true if modification time for the resource was updated.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies read access to the file (in the case of a file/directory-backed resource)

    • toExternalURI

      URI toExternalURI()
      Constructs a URI that represents this wrapped resource. The exact form of the URI may be system-dependent, and may or may not use a well-known scheme (like file).

      If it can be determined that this is resource is a directory, the resulting URI will end with a slash.

      Returns:
      a URI representing this resource with a defined scheme, but possibly undefined authority, query, and fragment components.

    • asFile

      File asFile()
      Returns the file backing this wrapped resource.
      Returns:
      the File backing this resource, or null.

    • toRepositoryPath

      String toRepositoryPath()
      Constructs a String that represents this wrapped resource using symbolic roots. The returned String will be suitable for use with WsLocationAdmin.resolveResource(String) or resolveRelative(String).

      If it can be determined that this is resource is a directory, the resulting URI will end with a slash.

      Returns:
      a relative URI (no scheme, etc.) representing this resource using symbolic elements.