com.ibm.wsspi.kernel.service.location
Interface WsResource
- public interface WsResource
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.
Nested Class Summary
Modifier and Type | Interface and Description |
---|---|
|
WsResource.Type
|
Method Summary
Modifier and Type | Method and Description |
---|---|
|
asFile()
Returns the file backing this wrapped resource.
|
|
create()
Creates a resource if it does not exist.
|
|
delete()
Deletes the wrapped/proxied resource.
|
|
exists()
Tests whether the wrapped/proxied resource exists.
|
|
get()
Creates and returns an InputStream for reading the contents of the
wrapped/proxied resource.
|
|
getChannel()
Creates and returns a ReadableByteChannel for reading the contents of the
wrapped/proxied resource.
|
getChild(java.lang.String name)
Obtain an WsResource for the named child (direct descendant of this
resource).
|
|
|
getChildren()
Returns an Iterator that will iterate over the names of each of the
children of this directory.
|
|
getChildren(java.lang.String resourceRegex)
Find the children whose names match the provided regular expression.
|
|
getLastModified()
Returns the time that the wrapped/proxied resource was last modified.
|
|
getName()
Returns the name of this resource.
|
getParent()
Obtain an WsResource for the parent of this resource.
|
|
getType()
Return the resource type
|
|
|
isType(WsResource.Type resourceType)
Tests whether the wrapped/proxied resource is of the specified type:
WsResource.Type .
|
|
length()
Returns the length of the wrapped/proxied resource.
|
|
moveTo(WsResource target)
Moves this resource to the target resource.
|
|
put(java.io.InputStream source)
Create or replace the content of this resource with the contents of the
provided InputStream.
|
|
put(java.nio.channels.ReadableByteChannel source)
Create or replace the content of this resource with the contents of the
provided ReadableByteChannel.
|
|
putChannel()
Creates and returns a WritableByteChannel which can be used to replace
the contents of the named resource.
|
|
putStream()
Creates and returns an OutputStream which can be used to replace the
contents of the named resource.
|
resolveRelative(java.lang.String relativeResourceURI)
Resolve an WsResource relative to the current resource/location.
|
|
|
setLastModified(long lastModified)
Set the time that the wrapped/proxied resource was last modified.
|
|
toExternalURI()
Constructs a URI that represents this wrapped resource.
|
|
toRepositoryPath()
Constructs a String that represents this wrapped resource using symbolic
roots.
|
Method Detail
create
- boolean create()
true
if and only if the wrapped/proxied resource is
successfully created; false
otherwise. 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
- boolean delete()
true
if and only if the wrapped/proxied resource is
successfully deleted; false
otherwise 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
- boolean exists()
true
if and only if the wrapped resource exists; false
otherwise 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
- java.io.InputStream get()
- throws java.io.IOException
The caller is responsible for closing the returned input stream.
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
- java.nio.channels.ReadableByteChannel getChannel( )
- throws java.io.IOException
The caller is responsible for closing the returned nio channel.
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
- WsResource getChild(java.lang.String name)
Note that this method returns null when the child does not exist. This differs from resolve(String) which never returns null.
name
- Name of child; can not contain path separator characters 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. 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
- java.util.Iterator<java.lang.String> getChildren( )
There is no guarantee that the names returned by the iterator will be in any specific order.
Not thread safe.
Iterator
that will iterate over a collection of String
s 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. 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
- java.util.Iterator<java.lang.String> getChildren( java.lang.String resourceRegex)
The iterator will present the matching names in the order they were matched. If no resources were found, the iterator will have no elements.
String.matches(String)
getLastModified
- long getLastModified()
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 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
- java.lang.String getName()
getParent
- WsResource getParent()
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
- WsResource.Type getType()
isType
- boolean isType(WsResource.Type resourceType)
WsResource.Type
. The resource must exist for its type to be determined.
true
if and only if the wrapped/proxied resource
exists and matches the specified type; false
otherwise. java.lang.SecurityException
- If a security manager exists and its SecurityManager.checkRead(java.lang.String)
method denies read access to the file length
- long length()
java.lang.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 java.io.IOException
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.
target
- The resolved WsResource that this resource should be moved
to. 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
- void put(java.io.InputStream source)
- throws java.io.IOException
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.
source
- InputStream containing the new contents of the resource.
Method will return with no action if the source is null or
empty. 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
- void put(java.nio.channels.ReadableByteChannel source)
- throws java.io.IOException
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.
source
- NIO ReadableByteChannel containing the new contents of the
resource. Method will return with no action if the source is
null or empty. 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. ReadableByteChannel
putStream
- java.io.OutputStream putStream( )
- throws java.io.IOException
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.
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
- java.nio.channels.WritableByteChannel putChannel( )
- throws java.io.IOException
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.
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
- WsResource resolveRelative(java.lang.String relativeResourceURI)
- 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.
relativeResourceURI
- String describing the artifact to resolve. Be sure to include
the terminator when resolving a directory. 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). URI.URI(String)
,
URI.URI(String, String, String, String)
setLastModified
- boolean setLastModified(long lastModified)
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 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
- java.net.URI toExternalURI()
If it can be determined that this is resource is a directory, the resulting URI will end with a slash.
asFile
- java.io.File asFile()
toRepositoryPath
- java.lang.String toRepositoryPath( )
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.
If the resource is a file, (
put(InputStream)
,put(ReadableByteChannel)
,putChannel()
, orputStream()
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.