de.intarsys.tools.locator
Interface ILocator

All Superinterfaces:
ISynchronizable
All Known Implementing Classes:
ByteArrayLocator, ClassLoaderResourceLocator, ClassResourceLocator, CommonLocator, DelegatingLocator, FileLocator, LocatorByReference, LocatorViewport, NullLocator, ReadOnlyLocator, StreamLocator, StringLocator, TransientLocator

public interface ILocator
extends ISynchronizable

The locator specifies the physical location of a resource.


Method Summary
 void delete()
          Delete the artifact referenced by this.
 boolean exists()
          Answer true if the location designated by this exists.
 ILocator getChild(java.lang.String name)
          The locator for the resource name within the context of this.
 java.lang.String getFullName()
          The full physical name of this.
 java.io.InputStream getInputStream()
          Return an InputStream on the data represented by the receiver.
 long getLength()
          Returns the length of this data container or -1 if unknown
 java.lang.String getLocalName()
          The local name of the receiver within its parent.
 java.io.OutputStream getOutputStream()
          Return an OutputStream on the location represented by the receiver.
 ILocator getParent()
          The ILocator that is one hierarchy level up or null.
 IRandomAccess getRandomAccess()
          The IRandomAccess for this.
 java.io.Reader getReader()
          A Reader on the data represented by the receiver.
 java.io.Reader getReader(java.lang.String encoding)
          A Reader on the data represented by the receiver for the given encoding.
 java.lang.String getType()
          The type of the resource.
 java.lang.String getTypedName()
          The qualified local name of the receiver within its parent that includes the type specification for the destination if appropriate.
 java.io.Writer getWriter()
          A Writer on the location represented by the receiver.
 java.io.Writer getWriter(java.lang.String encoding)
          A Writer on the location represented by the receiver for the given encoding.
 boolean isDirectory()
          Answer true if the location designated by this is a directory.
 boolean isReadOnly()
          true if the specified resource is read only.
 ILocator[] listLocators(ILocatorNameFilter filter)
          Return an array of ILocator that are children of the receiver that conform to filter.
 void rename(java.lang.String newName)
          Rename the complete physical name to newName.
 void setReadOnly()
          Make the receiver read only.
 java.net.URL toURL()
          The location designated by this as an URL.
 
Methods inherited from interface de.intarsys.tools.component.ISynchronizable
isOutOfSynch, synch
 

Method Detail

delete

void delete()
            throws java.io.IOException
Delete the artifact referenced by this.

Throws:
java.io.IOException

exists

boolean exists()
Answer true if the location designated by this exists.

Returns:
Answer true if the location designated by this exists.

getChild

ILocator getChild(java.lang.String name)
The locator for the resource name within the context of this. This may for example be an ILocator to a file within a directory.

Parameters:
name - The name of the resource to be located.
Returns:
The ILocator for the resource with the name "name" within the context of this.

getFullName

java.lang.String getFullName()
The full physical name of this.

This method returns a representation that is proprietary to the underlying physical representation, for example a file name, a SQL statement or so on.

Returns:
The full physical name of the receiver.

getInputStream

java.io.InputStream getInputStream()
                                   throws java.io.IOException
Return an InputStream on the data represented by the receiver.

Returns:
An InputStream on the data represented by the receiver.
Throws:
java.io.IOException

getLength

long getLength()
               throws java.io.IOException
Returns the length of this data container or -1 if unknown

Returns:
the length of this data container, measured in bytes.
Throws:
java.io.IOException - if an I/O error occurs.

getLocalName

java.lang.String getLocalName()
The local name of the receiver within its parent.

Returns:
The local name of the receiver within its parent.

getOutputStream

java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
Return an OutputStream on the location represented by the receiver.

Returns:
An OutputStream on the location represented by the receiver.
Throws:
java.io.IOException

getParent

ILocator getParent()
The ILocator that is one hierarchy level up or null. This may be for example the directory where the currently designated resource is found.

Returns:
The ILocatorthat is one hierarchy level up or null.

getRandomAccess

IRandomAccess getRandomAccess()
                              throws java.io.IOException
The IRandomAccess for this.

Returns:
The IRandomAccess for this.
Throws:
java.io.IOException

getReader

java.io.Reader getReader()
                         throws java.io.IOException
A Reader on the data represented by the receiver.

Returns:
A Reader on the data represented by the receiver.
Throws:
java.io.IOException

getReader

java.io.Reader getReader(java.lang.String encoding)
                         throws java.io.IOException
A Reader on the data represented by the receiver for the given encoding.

Parameters:
encoding - The encoding.
Returns:
A Reader on the data represented by the receiver for the given encoding.
Throws:
java.io.IOException

getType

java.lang.String getType()
The type of the resource. This may be for example a mime type or the file extension of the underlying file.

Returns:
The type of the resource

getTypedName

java.lang.String getTypedName()
The qualified local name of the receiver within its parent that includes the type specification for the destination if appropriate. This is for example a filename with its correct suffix. Some locator may return the same name as "getLocalName".

Returns:
The qualified local name of the receiver within its parent that includes the type specification for the destination if appropriate.

getWriter

java.io.Writer getWriter()
                         throws java.io.IOException
A Writer on the location represented by the receiver.

Returns:
A Writer on the location represented by the receiver.
Throws:
java.io.IOException

getWriter

java.io.Writer getWriter(java.lang.String encoding)
                         throws java.io.IOException
A Writer on the location represented by the receiver for the given encoding.

Parameters:
encoding - The encoding.
Returns:
A Writer on the location represented by the receiver for the given encoding.
Throws:
java.io.IOException

isDirectory

boolean isDirectory()
Answer true if the location designated by this is a directory. A directory location serves as a container for other resources, you can never getInputStream on this.

Returns:
Answer true if the location designated by this is a directory.

isReadOnly

boolean isReadOnly()
true if the specified resource is read only.

Returns:
true if the specified resource is read only.

listLocators

ILocator[] listLocators(ILocatorNameFilter filter)
                        throws java.io.IOException
Return an array of ILocator that are children of the receiver that conform to filter. This method never returns null.

Parameters:
filter - The filter used to examine the child resources.
Returns:
An array of ILocator objects that conform to the filter argument.
Throws:
java.io.IOException

rename

void rename(java.lang.String newName)
            throws java.io.IOException
Rename the complete physical name to newName.

Parameters:
newName - The new name of the ILocator. The new name is expected to contain both local and type part of the name.
Throws:
java.io.IOException

setReadOnly

void setReadOnly()
Make the receiver read only. This is a one way switch only.


toURL

java.net.URL toURL()
The location designated by this as an URL.

Returns:
The location designated by this as an URL.