edu.mit.jsemcor.main
Class URLConcordance

java.lang.Object
  edu.mit.jsemcor.main.URLConcordance

All Implemented Interfaces:

IConcordance, Iterable<IContext>

Direct Known Subclasses:

FileConcordance

public abstract class URLConcordance
extends Object
implements IConcordance

This abstract implementation of the IConcordance interface is appropriate for all concordances that retrieve their data from URLs. This implementation has basic facilities for a size-limited LRU cache. Caching, the cache size limit, can be set with the constructors, or the appropriate methods.

Since:

JSemcor 1.0.0

Version:

1.156, 16 Dec 2008

Author:

M.A. Finlayson

Nested Class Summary

protected class

URLConcordance.ContextIterator Delivers context objects in order from this concordance.

Field Summary

protected Map<IContextID,IContext>	cache The cache where context objects are stored.
protected Map<IContextID,URL>	contextMap The map that contains IContextID objects mapped to their URL locations.
static int	DEFAULT_CACHE_LIMIT The default cache size
protected IContextParser	parser The context parser used by this concordance to translate context data into IContext objects.

Constructor Summary

URLConcordance(URL url)
Constructs a new concordance whose base directory is the specified URL.

URLConcordance(URL url, boolean cache)
Constructs a new concordance whose base directory is the specified URL, with caching turned on or off according to the flag.

URLConcordance(URL url, boolean cache, int cacheLimit)
Constructs a new concordance whose base directory is the specified URL, with caching turned on or off according to the flag, and the specified cache limit.

Method Summary

protected void	checkOpen() If the concordance is not open, calling this method will result in a ConcordanceClosedException; if the provider is open, nothing will happen.
void	close() This closes the concordance by disposing of data backing objects or connections.
protected abstract ITagIndex	createTagIndex() This method is called during open() to construct the tag index object.
protected abstract String	extractConcordanceName(URL url) Returns the concordance name given the concordance URL.
protected abstract boolean	fillContextURLMap(Map<IContextID,URL> map) This method is called during open() to construct a map from context id objects to the URLs from which the context contents can be downloaded.
Map<IContextID,IContext>	getCache() Returns the actual cache map object, so that it can be directly manipulated by clients.
int	getCacheLimit() Returns the current cache limit set on this concordance set
IContext	getContext(IContextID id) A convenience method that first checks to see if the IContextID.getContextName() equals this concordance's name; if so, the result is the same as calling IConcordance.getContext(String).
IContext	getContext(String contextName) A convenience method, identical to IConcordance.getContext(IContextID)
Set<IContextID>	getContextIDs() Returns a set of context id objects for all contexts in this concordance.
String	getName() Returns the name of the concordance, which is a non-null, non-empty string.
protected IContextParser	getParser() Returns the parser that should be used to parse raw context contents into an IContext object.
ITagIndex	getTagIndex() Returns the tag index object for this concordance, if one exists.
URL	getURL() Returns the URL that points to the root directory of this concordance.
boolean	isCaching() Returns whether this concordance is currently caching the results of calls to getContext(IContextID).
boolean	isOpen() Returns whether the concordance is in a state such that it can provide context objects on demand.
Iterator<IContext>	iterator() Returns an iterator over context objects contained in this concordance.
protected IContextParser	makeParser() Returns a new instance of the parser that should be used to parse raw context contents into an IContext object.
boolean	open() Performs all the necessary operations to prepare this concordance to provide contexts.
protected void	pruneCache() Removes items from the cache so that the cache size is below the cache limit.
boolean	setCacheLimit(int limit) Sets the cache limit on this concordance.
boolean	setCaching(boolean value) Turns caching on or off for this concordance.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CACHE_LIMIT

public static final int DEFAULT_CACHE_LIMIT

The default cache size

Since:

JSemcor 1.0.0

See Also:

Constant Field Values

parser

protected IContextParser parser

The context parser used by this concordance to translate context data into IContext objects.

Since:

JSemcor 1.0.0

contextMap

protected final Map<IContextID,URL> contextMap

The map that contains IContextID objects mapped to their URL locations.

Since:

JSemcor 1.0.0

cache

protected Map<IContextID,IContext> cache

The cache where context objects are stored.

Since:

JSemcor 1.0.0

Constructor Detail

URLConcordance

public URLConcordance(URL url)

Constructs a new concordance whose base directory is the specified URL. Caching is by default on.

Throws:

NullPointerException - if the specified URL is null

Since:

JSemcor 1.0.0

URLConcordance

public URLConcordance(URL url,
                      boolean cache)

Constructs a new concordance whose base directory is the specified URL, with caching turned on or off according to the flag.

Throws:

NullPointerException - if the specified URL is null

Since:

JSemcor 1.0.0

URLConcordance

public URLConcordance(URL url,
                      boolean cache,
                      int cacheLimit)

Constructs a new concordance whose base directory is the specified URL, with caching turned on or off according to the flag, and the specified cache limit.

Throws:

NullPointerException - if the specified URL is null

Since:

JSemcor 1.0.0

Method Detail

getName

public String getName()

Description copied from interface: IConcordance

Returns the name of the concordance, which is a non-null, non-empty string. For example, Semcor contains three concordances with the names brown1, brown2, and brownv. This string will be equal to that returned by IContextID.getConcordanceName() method for contexts in this concordance.

Specified by:

getName in interface IConcordance

getURL

public URL getURL()

Returns the URL that points to the root directory of this concordance.

Returns:

the URL that points to the base directory of this concordance.

Since:

JSemcor 1.0.0

open

public boolean open()

Description copied from interface: IConcordance

Performs all the necessary operations to prepare this concordance to provide contexts. This may include connecting to this concordance source URL, discovering the directory structure and file lists, and building maps from context names to context locations. The return value of this method indicates if the operations were successful or not. If this method returns false, then subsequent calls to IConcordance.isOpen() will return false as well. If the concordance is already open, this method does nothing.

Specified by:

open in interface IConcordance

Returns:

true if there were no errors in initialization; false otherwise.

extractConcordanceName

protected abstract String extractConcordanceName(URL url)

Returns the concordance name given the concordance URL. This method is called in the URLConcordance constructor to extract the concordance's name from the specified URL.

Returns:

the concordance name for the specified URL

Throws:

NullPointerException - if the specified URL is null

Since:

JSemcor 1.0.0

fillContextURLMap

protected abstract boolean fillContextURLMap(Map<IContextID,URL> map)
                                      throws IOException

This method is called during open() to construct a map from context id objects to the URLs from which the context contents can be downloaded.

Returns:

true if the operation completed successfully; false otherwise.

Throws:

IOException - if there is a problem extracting the list of context ids from the root URL location.

Since:

JSemcor 1.0.0

createTagIndex

protected abstract ITagIndex createTagIndex()
                                     throws IOException

This method is called during open() to construct the tag index object. If this concordance does not contain the necessary data to create the tag index, this method will return null.

Returns:

The ITagIndex for this concordance, or null if no tag index exists.

Throws:

IOException - if there is an IO error when creating the tag index.

Since:

JSemcor 1.0.0

getParser

protected IContextParser getParser()

Returns the parser that should be used to parse raw context contents into an IContext object. This method returns the singleton instance of the parser that this concordance uses. If subclasses which to change the parser, they should override the makeParser() method.

Returns:

the context parser for this concordance.

Since:

JSemcor 1.0.0

makeParser

protected IContextParser makeParser()

Returns a new instance of the parser that should be used to parse raw context contents into an IContext object. Usually this method is only ever called once, to create the parser when it is first requested. The URLConcordance implementation then caches that instance and returns on future requests for a parser.

Returns:

a new instance of the context parser that should be used to parse context data into IContext objects.

Since:

JSemcor 1.0.0

checkOpen

protected void checkOpen()

If the concordance is not open, calling this method will result in a ConcordanceClosedException; if the provider is open, nothing will happen.

Throws:

ConcordanceClosedException - if the concordance is closed

Since:

JSemcor 1.0.0

isOpen

public boolean isOpen()

Description copied from interface: IConcordance

Returns whether the concordance is in a state such that it can provide context objects on demand.

Specified by:

isOpen in interface IConcordance

Returns:

true if the concordance is open; false otherwise.

close

public void close()

Description copied from interface: IConcordance

This closes the concordance by disposing of data backing objects or connections. It should not be irreversible, though: another call to IConcordance.open() should put the concordance back in the ready state. If the concordance is already closed, this method does nothing.

Specified by:

close in interface IConcordance

getContextIDs

public Set<IContextID> getContextIDs()

Description copied from interface: IConcordance

Returns a set of context id objects for all contexts in this concordance. The set may or may not be ordered, depending on the actual structures backing this object.

Specified by:

getContextIDs in interface IConcordance

getTagIndex

public ITagIndex getTagIndex()

Description copied from interface: IConcordance

Returns the tag index object for this concordance, if one exists. If not, returns null.

Specified by:

getTagIndex in interface IConcordance

Returns:

an ITagIndex object, if one can be created; otherwise, null

getContext

public IContext getContext(String contextName)

Description copied from interface: IConcordance

A convenience method, identical to IConcordance.getContext(IContextID)

Specified by:

getContext in interface IConcordance

Returns:

the identified context, if it can be found; null otherwise.

getContext

public IContext getContext(IContextID id)

Description copied from interface: IConcordance

A convenience method that first checks to see if the IContextID.getContextName() equals this concordance's name; if so, the result is the same as calling IConcordance.getContext(String). If not, returns null.

Specified by:

getContext in interface IConcordance

Returns:

the identified context, if it can be found; null otherwise.

iterator

public Iterator<IContext> iterator()

Description copied from interface: IConcordance

Returns an iterator over context objects contained in this concordance.

Specified by:

iterator in interface IConcordance

Specified by:

iterator in interface Iterable<IContext>

Returns:

an iterator that returns IContext objects.

See Also:

Iterable.iterator()

isCaching

public boolean isCaching()

Returns whether this concordance is currently caching the results of calls to getContext(IContextID).

setCaching

public boolean setCaching(boolean value)

Turns caching on or off for this concordance. Turning caching off with the method does not clear that cache, it merely prevents any future contexts retrieved from being cached. If a context object is already in the cache, that context will be returned when it's id is requested from the getContext(IContextID) method. To clear the cache, obtain the cache map instance via getCache() method and call Map.clear().

setCacheLimit

public boolean setCacheLimit(int limit)

Sets the cache limit on this concordance. Returns a flag indicating this call actually changed the cache limit. The method does not allow the cache limit to be set less than 1; if a number less than 1 is specified, the cache limit is set to 1. If the cache size is greater than the new cache limit, the cache is pruned down to size. To turn off caching, use the setCaching(boolean) method.

Returns:

true if the cache limit was changed; false otherwise

getCacheLimit

public int getCacheLimit()

Returns the current cache limit set on this concordance set

Returns:

the current cache limit.

getCache

public Map<IContextID,IContext> getCache()

Returns the actual cache map object, so that it can be directly manipulated by clients.

Returns:

the cache in use by the concordance.

pruneCache

protected void pruneCache()

Removes items from the cache so that the cache size is below the cache limit. If the cache size is already less than the cache limit, this method does nothing.