com.threecrickets.scripturian.document

Class DocumentFileSource<D>

java.lang.Object

com.threecrickets.scripturian.document.DocumentFileSource<D>

Type Parameters:

D - The document type

All Implemented Interfaces:

DocumentSource<D>

public class DocumentFileSource<D>
extends Object
implements DocumentSource<D>

Reads document stored in files under a base directory. The file contents are cached, and checked for validity according to their modification timestamps. The validity check is cascaded according to the dependency tree (see DocumentDescriptor.getDependencies().

Documents added to the file source exist only in memory, and are not actually saved to a file.

Author:

Tal Liron

Field Summary

Fields

Modifier and Type	Field and Description
static String	IGNORE_POSTFIXES_VARIABLE Name of environment variable for ignoring filename postfixes.

Constructor Summary

Constructors

Constructor and Description
DocumentFileSource(File basePath, String defaultName, String preferredExtension, long minimumTimeBetweenValidityChecks) Constructs a document file source.
DocumentFileSource(String identifier, File basePath, String defaultName, String preferredExtension, long minimumTimeBetweenValidityChecks) Constructs a document file source.
DocumentFileSource(String identifier, File basePath, String defaultName, String preferredExtension, String preExtension, long minimumTimeBetweenValidityChecks) Constructs a document file source.

Method Summary

Modifier and Type	Method and Description
File	getBasePath() The base path.
com.threecrickets.scripturian.internal.FiledDocumentDescriptor<D>	getCachedDocumentDescriptor(String documentName) Gets a document descriptor for the document if it's in the cache.
Charset	getCharset() The charset to use for reading files.
String	getDefaultName() If the name used in getDocument(String) points to a directory, then this file name in that directory will be used instead.
DocumentDescriptor<D>	getDocument(String documentName) Gets a document by its name.
DocumentDescriptor<D>	getDocument(String documentName, boolean read) Gets the document descriptor, with support for caching descriptors.
Collection<DocumentDescriptor<D>>	getDocuments() Access to all available documents.
String	getIdentifier() The identifier for this document source.
CopyOnWriteArrayList<String>	getIgnorePostfixes() The filename postfixes to ignore.
long	getMinimumTimeBetweenValidityChecks() Attempts to call getDocument(String) for a specific name within less than this time from the previous call will return the cached descriptor without checking if it is valid.
String	getPreExtension() An optional magic "pre-extension" to require for all documents.
String	getPreferredExtension() An extension to prefer if more than one file with the same name is in a directory.
String	getRelativeFilePath(File file) Gets the file's path relative to the base path.
void	setCharset(Charset charset)
void	setDefaultName(String defaultName)
DocumentDescriptor<D>	setDocument(String documentName, String sourceCode, String tag, D document) Allows adding or changing documents.
DocumentDescriptor<D>	setDocumentIfAbsent(String documentName, String sourceCode, String tag, D document) Allows for atomically adding or changing documents.
void	setMinimumTimeBetweenValidityChecks(long minimumTimeBetweenValidityChecks)
void	setPreExtension(String preExtension)
void	setPreferredExtension(String preferredExtension)
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

IGNORE_POSTFIXES_VARIABLE

public static final String IGNORE_POSTFIXES_VARIABLE

Name of environment variable for ignoring filename postfixes.

See Also:

Constant Field Values

Constructor Detail

DocumentFileSource

public DocumentFileSource(File basePath,
                          String defaultName,
                          String preferredExtension,
                          long minimumTimeBetweenValidityChecks)

Constructs a document file source. The identifier will be the base path.

Parameters:

basePath - The base path

defaultName - If the name used in getDocument(String) points to a directory, then this file name in that directory will be used instead; note that if an extension is not specified, then the first file in the directory with this name, with any extension, will be used

preferredExtension - An extension to prefer if more than one file with the same name is in a directory

minimumTimeBetweenValidityChecks - See getMinimumTimeBetweenValidityChecks()

DocumentFileSource

public DocumentFileSource(String identifier,
                          File basePath,
                          String defaultName,
                          String preferredExtension,
                          long minimumTimeBetweenValidityChecks)

Constructs a document file source.

Parameters:

identifier - The identifier

basePath - The base path

defaultName - If the name used in getDocument(String) points to a directory, then this file name in that directory will be used instead; note that if an extension is not specified, then the first file in the directory with this name, with any extension, will be used

preferredExtension - An extension to prefer if more than one file with the same name is in a directory

minimumTimeBetweenValidityChecks - See getMinimumTimeBetweenValidityChecks()

DocumentFileSource

public DocumentFileSource(String identifier,
                          File basePath,
                          String defaultName,
                          String preferredExtension,
                          String preExtension,
                          long minimumTimeBetweenValidityChecks)

Constructs a document file source.

Parameters:

identifier - The identifier

basePath - The base path

defaultName - If the name used in getDocument(String) points to a directory, then this file name in that directory will be used instead; note that if an extension is not specified, then the first file in the directory with this name, with any extension, will be used

preferredExtension - An extension to prefer if more than one file with the same name is in a directory

preExtension - An optional magic "pre-extension" to require for all documents

minimumTimeBetweenValidityChecks - See getMinimumTimeBetweenValidityChecks()

Method Detail

getBasePath

public File getBasePath()

The base path.

Returns:

The base path

getDefaultName

public String getDefaultName()

If the name used in getDocument(String) points to a directory, then this file name in that directory will be used instead. If an extension is not specified, then the preferred extension will be used.

Returns:

The default name

See Also:

setDefaultName(String)

setDefaultName

public void setDefaultName(String defaultName)

Parameters:

defaultName - The default name

See Also:

getDefaultName()

getPreferredExtension

public String getPreferredExtension()

An extension to prefer if more than one file with the same name is in a directory.

Returns:

The preferred extension

See Also:

setPreferredExtension(String)

setPreferredExtension

public void setPreferredExtension(String preferredExtension)

Parameters:

preferredExtension - The preferred extension

See Also:

getPreferredExtension()

getPreExtension

public String getPreExtension()

An optional magic "pre-extension" to require for all documents.

Returns:

The pre-extension

See Also:

setPreExtension(String)

setPreExtension

public void setPreExtension(String preExtension)

Parameters:

preExtension - The pre-extension

See Also:

getPreExtension()

getIgnorePostfixes

public CopyOnWriteArrayList<String> getIgnorePostfixes()

The filename postfixes to ignore.

Returns:

The postfixes

getMinimumTimeBetweenValidityChecks

public long getMinimumTimeBetweenValidityChecks()

Attempts to call getDocument(String) for a specific name within less than this time from the previous call will return the cached descriptor without checking if it is valid. A value of -1 disables all validity checking.

Returns:

The minimum time between validity checks in milliseconds

See Also:

setMinimumTimeBetweenValidityChecks(long)

setMinimumTimeBetweenValidityChecks

public void setMinimumTimeBetweenValidityChecks(long minimumTimeBetweenValidityChecks)

Parameters:

minimumTimeBetweenValidityChecks - The minimum time between validity checks in milliseconds

See Also:

getMinimumTimeBetweenValidityChecks()

getCharset

public Charset getCharset()

The charset to use for reading files.

Note that the default is always UTF-8, not the underlying JVM's default charset, which may be inconsistently set across diverse runtime environments.

Returns:

The charset

See Also:

setCharset(Charset)

setCharset

public void setCharset(Charset charset)

Parameters:

charset - The charset

See Also:

getCharset()

getRelativeFilePath

public String getRelativeFilePath(File file)

Gets the file's path relative to the base path.

Parameters:

file - The file

Returns:

The path

getCachedDocumentDescriptor

public com.threecrickets.scripturian.internal.FiledDocumentDescriptor<D> getCachedDocumentDescriptor(String documentName)

Gets a document descriptor for the document if it's in the cache. Otherwise, returns null.

Parameters:

documentName - The document name

Returns:

The document descriptor or null

getDocument

public DocumentDescriptor<D> getDocument(String documentName,
                                         boolean read)
                                  throws DocumentException

Gets the document descriptor, with support for caching descriptors. The cached descriptor will be reset if the document file is updated since the last call. In order to avoid checking this every time this method is called, use setMinimumTimeBetweenValidityChecks(long).

Parameters:

documentName - The document name

read - Whether to read the source code from the file

Returns:

The document descriptor

Throws:

DocumentException - In case of a document retrieval error

getDocument

public DocumentDescriptor<D> getDocument(String documentName)
                                  throws DocumentException

Description copied from interface: DocumentSource

Gets a document by its name.

Specified by:

getDocument in interface DocumentSource<D>

Parameters:

documentName - The document's name

Returns:

The document's descriptor

Throws:

DocumentException - In case of a document retrieval error

See Also:

DocumentSource.getDocument(String)

setDocument

public DocumentDescriptor<D> setDocument(String documentName,
                                         String sourceCode,
                                         String tag,
                                         D document)
                                  throws DocumentException

Description copied from interface: DocumentSource

Allows adding or changing documents.

Specified by:

setDocument in interface DocumentSource<D>

Parameters:

documentName - The document's name

sourceCode - The source code for the document

tag - The tag

document - The document

Returns:

The existing document descriptor before we changed it

Throws:

DocumentException - In case of a document retrieval error

See Also:

DocumentSource.setDocument(String, String, String, Object)

setDocumentIfAbsent

public DocumentDescriptor<D> setDocumentIfAbsent(String documentName,
                                                 String sourceCode,
                                                 String tag,
                                                 D document)
                                          throws DocumentException

Description copied from interface: DocumentSource

Allows for atomically adding or changing documents.

Specified by:

setDocumentIfAbsent in interface DocumentSource<D>

Parameters:

documentName - The document's name

sourceCode - The source code for the document

tag - The tag

document - The document instance

Returns:

The existing document descriptor before we changed it

Throws:

DocumentException - In case of a document retrieval error

See Also:

DocumentSource.setDocumentIfAbsent(String, String, String, Object)

getDocuments

public Collection<DocumentDescriptor<D>> getDocuments()

Description copied from interface: DocumentSource

Access to all available documents.

Note that not all implementations support this operation.

Specified by:

getDocuments in interface DocumentSource<D>

Returns:

A collection of document descriptors

See Also:

DocumentSource.getDocuments()

getIdentifier

public String getIdentifier()

Description copied from interface: DocumentSource

The identifier for this document source.

Specified by:

getIdentifier in interface DocumentSource<D>

Returns:

The identifier

See Also:

DocumentSource.getIdentifier()

toString

public String toString()

Overrides:

toString in class Object