org.restlet.resource

## Class Directory

- java.lang.Object
- - org.restlet.Restlet
  - - org.restlet.resource.Finder
    - - org.restlet.resource.Directory

All Implemented Interfaces:
  Uniform

    public class Directory
    extends Finder

Finder mapping a directory of local resources. Those resources have representations accessed by the file system, the class loaders or other URI accessible protocols. Here is some sample code illustrating how to attach a directory to a router:

     Directory directory = new Directory(getContext(), "file:///user/data/files/");
     Router router = new Router(getContext());
     router.attach("/static/", directory);

An automatic content negotiation mechanism (similar to the one in Apache HTTP server) is used to select the best representation of a resource based on the available variants and on the client capabilities and preferences.
The directory can be used in read-only or modifiable mode. In the latter case, you just need to set the "modifiable" property to true. The currently supported methods are PUT and DELETE.
When no index is available in a given directory, a representation can be automatically generated by the `getIndexRepresentation(Variant, ReferenceList)` method, unless the "listingAllowed" property is turned off. You can even customize the way the index entries are sorted by using the `setComparator(Comparator)` method. The default sorting uses the friendly Alphanum algorithm based on David Koelle's original idea, using a different and faster implementation contributed by Rob Heittman.
Concurrency note: instances of this class or its subclasses can be invoked by several threads at the same time and therefore must be thread-safe. You should be especially careful when storing state in member variables.

Author:
  Jerome Louvel
See Also:
  User Guide - Serving static files

### Constructor Summary

Constructors
Constructor and Description
`Directory(Context context, Reference rootLocalReference)` Constructor.
`Directory(Context context, java.lang.String rootUri)` Constructor.

### Method Summary

Methods
`java.util.Comparator<Reference>` `getComparator()` Returns the reference comparator used to sort index pages.
`java.lang.String` `getIndexName()` Returns the index name, without extensions.
`Representation` `getIndexRepresentation(Variant variant, ReferenceList indexContent)` Returns an actual index representation for a given variant.
`java.util.List<Variant>` `getIndexVariants(ReferenceList indexContent)` Returns the variant representations of a directory index.
`Reference` `getRootRef()` Returns the root URI from which the relative resource URIs will be looked up.
`void` `handle(Request request, Response response)` Handles a call.
`boolean` `isDeeplyAccessible()` Indicates if the sub-directories are deeply accessible (true by default).
`boolean` `isListingAllowed()` Indicates if the display of directory listings is allowed when no index file is found.
`boolean` `isModifiable()` Indicates if modifications to local resources (most likely files) are allowed.
`boolean` `isNegotiateContent()` Deprecated. Use `isNegotiatingContent()` instead.
`boolean` `isNegotiatingContent()` Indicates if the best content is automatically negotiated.
`void` `setAlphaComparator()` Sets the reference comparator based on classic alphabetical order.
`void` `setAlphaNumComparator()` Sets the reference comparator based on the more friendly "Alphanum Algorithm" created by David Koelle.
`void` `setComparator(java.util.Comparator<Reference> comparator)` Sets the reference comparator used to sort index pages.
`void` `setDeeplyAccessible(boolean deeplyAccessible)` Indicates if the sub-directories are deeply accessible (true by default).
`void` `setIndexName(java.lang.String indexName)` Sets the index name, without extensions.
`void` `setListingAllowed(boolean listingAllowed)` Indicates if the display of directory listings is allowed when no index file is found.
`void` `setModifiable(boolean modifiable)` Indicates if modifications to local resources are allowed.
`void` `setNegotiateContent(boolean negotiatingContent)` Deprecated. Use `setNegotiatingContent(boolean)` instead.
`void` `setNegotiatingContent(boolean negotiatingContent)` Indicates if the best content is automatically negotiated.
`void` `setRootRef(Reference rootRef)` Sets the root URI from which the relative resource URIs will be lookep up.

### Methods inherited from class org.restlet.resource.Finder

`create, create, createFinder, createTarget, createTarget, find, findTarget, getTargetClass, setTargetClass`

### Methods inherited from class org.restlet.Restlet

`finalize, getApplication, getAuthor, getContext, getDescription, getLogger, getName, getOwner, isStarted, isStopped, setAuthor, setContext, setDescription, setName, setOwner, start, stop`

### Methods inherited from class java.lang.Object

`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### Directory

    public Directory(Context context,
             Reference rootLocalReference)

Constructor.

Parameters:
  `context` - The context.
  `rootLocalReference` - The root URI.

#### Directory

    public Directory(Context context,
             java.lang.String rootUri)

Constructor.

Parameters:
  `context` - The context.
  `rootUri` - The absolute root URI.
  If you serve files from the file system, use file:// URIs and make sure that you register a FILE connector with your parent Component. On Windows, make sure that you add enough slash characters at the beginning, for example: file:///c:/dir/file
  If you serve files from a class loader, use clap:// URIs and make sure that you register a CLAP connector with your parent Component.

### Method Detail

#### getComparator

    public java.util.Comparator<Reference> getComparator()

Returns the reference comparator used to sort index pages. The default implementation used a friendly alphanum sorting.

Returns:
  The reference comparator.
See Also:
  `setAlphaNumComparator()`

#### getIndexName

    public java.lang.String getIndexName()

Returns the index name, without extensions. Returns "index" by default.

Returns:
  The index name.

#### getIndexRepresentation

    public Representation getIndexRepresentation(Variant variant,
                                        ReferenceList indexContent)

Returns an actual index representation for a given variant.

Parameters:
  `variant` - The selected variant.
  `indexContent` - The directory index to represent.
Returns:
  The actual index representation.

#### getIndexVariants

    public java.util.List<Variant> getIndexVariants(ReferenceList indexContent)

Returns the variant representations of a directory index. This method can be subclassed in order to provide alternative representations. By default it returns a simple HTML document and a textual URI list as variants. Note that a new instance of the list is created for each call.

Parameters:
  `indexContent` - The list of references contained in the directory index.
Returns:
  The variant representations of a directory.

#### getRootRef

    public Reference getRootRef()

Returns the root URI from which the relative resource URIs will be looked up.

Returns:
  The root URI.

#### handle

    public void handle(Request request,
              Response response)

Description copied from class: `Finder`
Handles a call.

Specified by:
  `handle` in interface `Uniform`
Overrides:
  `handle` in class `Finder`
Parameters:
  `request` - The request to handle.
  `response` - The response to update.

#### isDeeplyAccessible

    public boolean isDeeplyAccessible()

Indicates if the sub-directories are deeply accessible (true by default).

Returns:
  True if the sub-directories are deeply accessible.

#### isListingAllowed

    public boolean isListingAllowed()

Indicates if the display of directory listings is allowed when no index file is found.

Returns:
  True if the display of directory listings is allowed when no index file is found.

#### isModifiable

    public boolean isModifiable()

Indicates if modifications to local resources (most likely files) are allowed. Returns false by default.

Returns:
  True if modifications to local resources are allowed.

#### isNegotiateContent

    @Deprecated
    public boolean isNegotiateContent()

Deprecated. Use `isNegotiatingContent()` instead.
Indicates if the best content is automatically negotiated. Default value is true.

Returns:
  True if the best content is automatically negotiated.

#### isNegotiatingContent

    public boolean isNegotiatingContent()

Indicates if the best content is automatically negotiated. Default value is true.

Returns:
  True if the best content is automatically negotiated.

#### setAlphaComparator

    public void setAlphaComparator()

Sets the reference comparator based on classic alphabetical order.

See Also:
  `setComparator(Comparator)`

#### setAlphaNumComparator

    public void setAlphaNumComparator()

Sets the reference comparator based on the more friendly "Alphanum Algorithm" created by David Koelle. The internal implementation used is based on an optimized public domain implementation provided by Rob Heittman from the Solertium Corporation.

See Also:
  The original Alphanum Algorithm from David Koelle, `setComparator(Comparator)`

#### setComparator

    public void setComparator(java.util.Comparator<Reference> comparator)

Sets the reference comparator used to sort index pages.

Parameters:
  `comparator` - The reference comparator.

#### setDeeplyAccessible

    public void setDeeplyAccessible(boolean deeplyAccessible)

Indicates if the sub-directories are deeply accessible (true by default).

Parameters:
  `deeplyAccessible` - True if the sub-directories are deeply accessible.

#### setIndexName

    public void setIndexName(java.lang.String indexName)

Sets the index name, without extensions.

Parameters:
  `indexName` - The index name.

#### setListingAllowed

    public void setListingAllowed(boolean listingAllowed)

Indicates if the display of directory listings is allowed when no index file is found.

Parameters:
  `listingAllowed` - True if the display of directory listings is allowed when no index file is found.

#### setModifiable

    public void setModifiable(boolean modifiable)

Indicates if modifications to local resources are allowed.

Parameters:
  `modifiable` - True if modifications to local resources are allowed.

#### setNegotiateContent

    @Deprecated
    public void setNegotiateContent(boolean negotiatingContent)

Deprecated. Use `setNegotiatingContent(boolean)` instead.
Indicates if the best content is automatically negotiated. Default value is true.

Parameters:
  `negotiatingContent` - True if the best content is automatically negotiated.

#### setNegotiatingContent

    public void setNegotiatingContent(boolean negotiatingContent)

Indicates if the best content is automatically negotiated. Default value is true.

Parameters:
  `negotiatingContent` - True if the best content is automatically negotiated.

#### setRootRef

    public void setRootRef(Reference rootRef)

Sets the root URI from which the relative resource URIs will be lookep up.

Parameters:
  `rootRef` - The root URI.