com.ibm.wsspi.kernel.service.location

Interface WsResource


  1. 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:
WsLocationAdmin

Nested Class Summary

Modifier and Type Interface and Description
  1. static class
WsResource.Type

Method Summary

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

Method Detail

create

  1. 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:
java.lang.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

  1. 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:
java.lang.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

  1. boolean exists()
Tests whether the wrapped/proxied resource exists.
Returns:
true if and only if the wrapped resource exists; false otherwise
Throws:
java.lang.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

  1. java.io.InputStream get()
  2. throws java.io.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:
java.lang.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)
java.io.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

  1. java.nio.channels.ReadableByteChannel getChannel( )
  2. throws java.io.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:
java.lang.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).
java.io.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

  1. WsResource getChild(java.lang.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:
java.lang.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.
java.lang.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

  1. java.util.Iterator<java.lang.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:
java.lang.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

  1. java.util.Iterator<java.lang.String> getChildren( java.lang.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.

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:
String.matches(String)

getLastModified

  1. 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:
java.lang.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

  1. java.lang.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

  1. 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:
java.lang.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)
java.lang.IllegalArgumentException - if parent resource already exists as a file.

getType

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

isType

  1. 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:
java.lang.SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

length

  1. 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:
java.lang.SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

moveTo

  1. boolean moveTo(WsResource target)
  2. throws java.io.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:
java.io.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.
java.lang.SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to either the old or new pathnames
java.lang.NullPointerException - If parameter target is null

put

  1. void put(java.io.InputStream source)
  2. throws java.io.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:
java.lang.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)
java.io.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

  1. void put(java.nio.channels.ReadableByteChannel source)
  2. throws java.io.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:
java.lang.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)
java.io.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:
ReadableByteChannel

putStream

  1. java.io.OutputStream putStream( )
  2. throws java.io.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:
java.lang.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)
java.io.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

  1. java.nio.channels.WritableByteChannel putChannel( )
  2. throws java.io.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:
java.lang.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)
java.io.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

  1. WsResource resolveRelative(java.lang.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.)
java.lang.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:
URI.URI(String), URI.URI(String, String, String, String)

setLastModified

  1. 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:
java.lang.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

  1. java.net.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

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

toRepositoryPath

  1. java.lang.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.