com.binaryfantasy.murq
Class Murq

java.lang.Object
  com.binaryfantasy.murq.Murq

public final class Murq
extends Object

The face of the Murq persistance library.

Murq is threadsafe as long as there is only one Murq instance per ISource destination. If two instances of Murq are created based on the same ISource instance, or two ISource instances pointing to the same repository, behavior will be nondeterministic.

Author:

Bill Weiss

Constructor Summary

Murq(ISource source)
Constructs a new instance using the specified source.

Murq(ISource source, String password)
Constructs a new instance using the specified source.

Method Summary

void	add(ISource src) Adds all content from the specified unencrypted src to this instance.
void	add(ISource src, String password) Adds all content from the specified src to this instance.
void	addContentListener(IContentListener listener) Adds a listener to be notified of ContentEvents.
void	addContentListener(IContentListener listener, Executor executor) Adds a listener to be notified of ContentEvents.
void	addLink(String linkName, String contentId) Provides a simple name link to the specified contentId.
void	close() Closes this Murq instance and releases resources.
protected void	finalize()
Set<IContent>	find(MurqQuery query) Performs a search of all content and returns a Set of matching content, or an empty Set if no matches are found.
Set<IContent>	find(String queryStr) Performs a search of all default content and returns a Set of matching content, or an empty Set if no matches are found.
Set<IContent>	find(String queryStr, Locale locale) Performs a search of all content relevant to the provided locale and returns a Set of matching content, or an empty Set if no matches are found.
Set<IContent>	find(String queryStr, Locale locale, String[] orderBy) Performs a search of all content relevant to the provided locale and returns a Set of matching content, or an empty Set if no matches are found.
Set<IContent>	findAll(String queryStr, String[] orderBy) Performs a search of the current contents using the Lucene search engine and returns a Set of ALL matching content objects - regardless of locale, or an empty Set if no matches are found.
IContent	findRandom(MurqQuery query) Returns a single, random IContent from the results returned from the specified query, or null if no matches are found.
IContent	get(String contentId) Returns the default content associated with the specified contentId, or null if no content is found.
IContent	get(String contentId, Locale locale) Returns the content associated with the specified contentId and relevant to the locale, or null if no content is found.
Set<IContent>	getAll(String contentId, String[] orderBy) Returns a Set of ALL content - regardless of locale - matching the specified contentId, or an empty Set if none are found.
Set<IContent>	getAllByClass(Class contentClass, String[] orderBy) Returns a Set of ALL content that is assignment-compatible with the contentClass and relevant to the locale, or an empty Set if none are found.
Set<IContent>	getByClass(Class contentClass) Returns a Set of all default content that is assignment-compatible with the contentClass, or an empty Set if none are found.
Set<IContent>	getByClass(Class contentClass, Locale locale, String[] orderBy) Returns a Set of content that is assignment-compatible with the contentClass and relevant to the locale, or an empty Set if none are found.
Set<IContent>	getByClass(Class contentClass, String[] orderBy) Returns a Set of all default content that is assignment-compatible with the contentClass, or an empty Set if none are found.
String	getId() Returns the unique id belonging to the ISource that backs the Murq facade.
Set<String>	getLinkNames() Returns all current link names.
Set<Locale>	getLocales(IContent content) Returns all Locales that the specified content is available in.
Set<Locale>	getLocales(String contentId) Returns all Locales that the specified contentId is available in.
ISource	getSource() Returns the ISource being used for persistance.
boolean	isOpen() Returns true if this Murq instance is open.
boolean	isUpdating() Returns true if there are ContentEvents being processed.
void	put(IContent content) Persists the specified content.
void	put(IContent content, boolean force) Persists the specified content, ignoring any possible concurrent modification issues if force is true.
int	read(String contentId, Locale locale, OutputStream out) Reads binary data relevant to the locale and associated with the contentId, writing it to the specified out.
int	read(String contentId, OutputStream out) Reads the default binary data associated with the contentId and writes it to the specified out.
boolean	remove(IContent content) Removes the specified content.
boolean	remove(String contentId, Locale locale) Removes the specified content.
boolean	removeAll(String contentId) Removes all content, in all locales, associated with the specified contentId.
void	removeContentListener(IContentListener listener) Removes a listener from being notified of ContentEvents.
void	removeLink(String linkName) Removes a simple name link.
void	removeLinks(String contentId) Removes all links associated with the contentId.
IContent	resolveLink(String linkName, Locale locale) Returns the IContent relevant to the locale targeted by the specified linkName, or null if none exists.
String	resolveLinkId(String linkName) Returns the contentId relevant to the specified linkName, or null if none exists.
IContent	resovleLink(String linkName) Returns the default IContent target of the specified linkName, or null if none exists.
String	toString()
int	write(IBinaryContent content, InputStream in) Persists the specified binary data from the in along with the metadata describing it in the content.
int	write(IBinaryContent content, InputStream in, boolean force) Persists the specified binary data from the in along with the metadata describing it in the content, ignoring any possible concurrent modification issues if force is true.

Methods inherited from class java.lang.Object

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

Constructor Detail

Murq

public Murq(ISource source)

Constructs a new instance using the specified source.

Parameters:

source - the initialized ISource persistance to be used.

Murq

public Murq(ISource source,
            String password)

Constructs a new instance using the specified source.

Parameters:

source - the initialized ISource persistance to be used.

password - if encrypted, null otherwise.

Method Detail

getId

public String getId()

Returns the unique id belonging to the ISource that backs the Murq facade.

Returns:

the unique id belonging to the ISource that backs the Murq facade.

getSource

public ISource getSource()

Returns the ISource being used for persistance.

NOTE: This method is intended for internal use only. Accessing and manipulating the ISource outside of Murq will result in nondeterministic behavior.

Returns:

the ISource being used for persistance.

isOpen

public boolean isOpen()

Returns true if this Murq instance is open.

Returns:

true if this Murq instance is open.

close

public void close()

Closes this Murq instance and releases resources. Attempts to use this instance after closing will result in a IllegalStateException.

Multiple calls to close have no effect.

addContentListener

public void addContentListener(IContentListener listener)

Adds a listener to be notified of ContentEvents.

Parameters:

listener - the object to be notified of ContentEvents.

Throws:

IllegalArgumentException - if listener is null.

addContentListener

public void addContentListener(IContentListener listener,
                               Executor executor)

Adds a listener to be notified of ContentEvents.

Parameters:

listener - the object to be notified of ContentEvents.

executor - the executor to use in firing events to this listener, or null to use default.

Throws:

IllegalArgumentException - if listener is null.

removeContentListener

public void removeContentListener(IContentListener listener)

Removes a listener from being notified of ContentEvents.

Parameters:

listener - the object to no longer be notified of ContentEvents.

Throws:

IllegalArgumentException - if listener is null.

findRandom

public IContent findRandom(MurqQuery query)

Returns a single, random IContent from the results returned from the specified query, or null if no matches are found.

Parameters:

query - defines the search, from which the random result will be selected.

Returns:

a single, random IContent from the results returned from the specified query, or null if no matches are found.

find

public Set<IContent> find(MurqQuery query)

Performs a search of all content and returns a Set of matching content, or an empty Set if no matches are found.

Parameters:

query - defines the search terms.

Returns:

the of matching content, or an empty Set if no matches are found.

Throws:

IllegalArgumentException - if the query is null.

IllegalStateException - if this Murq instance is closed.

find

public Set<IContent> find(String queryStr)

Performs a search of all default content and returns a Set of matching content, or an empty Set if no matches are found.

Parameters:

queryStr - a query string using Lucene query syntax.

Returns:

the matching content, or an empty Set if no matches are found.

Throws:

IllegalArgumentException - if the queryStr is null or if it cannot be parsed.

IllegalStateException - if this Murq instance is closed.

find

public Set<IContent> find(String queryStr,
                          Locale locale)

Performs a search of all content relevant to the provided locale and returns a Set of matching content, or an empty Set if no matches are found.

Parameters:

queryStr - a query string using Lucene query syntax.

locale - the locale releveant to the content to be found.

Returns:

the matching content, or an empty Set if no matches are found.

Throws:

IllegalArgumentException - if the queryStr is null or if it cannot be parsed.

IllegalStateException - if this Murq instance is closed.

find

public Set<IContent> find(String queryStr,
                          Locale locale,
                          String[] orderBy)

Performs a search of all content relevant to the provided locale and returns a Set of matching content, or an empty Set if no matches are found.

Parameters:

queryStr - a query string using Lucene query syntax.

orderBy - property names in order of precedence to order results by.

locale - the locale releveant to the content to be found.

Returns:

the matching content, or an empty Set if no matches are found.

Throws:

IllegalArgumentException - if the queryStr is null or if it cannot be parsed.

IllegalStateException - if this Murq instance is closed.

findAll

public Set<IContent> findAll(String queryStr,
                             String[] orderBy)

Performs a search of the current contents using the Lucene search engine and returns a Set of ALL matching content objects - regardless of locale, or an empty Set if no matches are found.

Parameters:

queryStr - the query to be executed.

orderBy - property names in order of precedence to order results by.

Returns:

the matching content objects, or an empty Set if no matches are found.

Throws:

IllegalStateException - if this Murq instance is closed.

IllegalArgumentException - if query is null.

getByClass

public Set<IContent> getByClass(Class contentClass)

Returns a Set of all default content that is assignment-compatible with the contentClass, or an empty Set if none are found.

Parameters:

contentClass - the assignment-compatible Class of the content to be found.

Returns:

a Set of all default content that is assignment-compatible with the contentClass, or an empty Set if none are found.

Throws:

IllegalArgumentException - if contentClass is null.

IllegalStateException - if this Murq instance is closed.

getByClass

public Set<IContent> getByClass(Class contentClass,
                                String[] orderBy)

Returns a Set of all default content that is assignment-compatible with the contentClass, or an empty Set if none are found.

Parameters:

contentClass - the assignment-compatible Class of the content to be found.

orderBy - property names in order of precedence to order results by.

Returns:

a Set of all default content that is assignment-compatible with the contentClass, or an empty Set if none are found.

Throws:

IllegalArgumentException - if contentClass is null.

IllegalStateException - if this Murq instance is closed.

getLocales

public Set<Locale> getLocales(IContent content)

Returns all Locales that the specified content is available in.

Parameters:

content - the IContent to check for available Locales.

Returns:

all Locales that the specified content is available in.

getLocales

public Set<Locale> getLocales(String contentId)

Returns all Locales that the specified contentId is available in.

Parameters:

contentId - the unique content identifier to check for available Locales.

Returns:

all Locales that the specified contentId is available in.

getByClass

public Set<IContent> getByClass(Class contentClass,
                                Locale locale,
                                String[] orderBy)

Returns a Set of content that is assignment-compatible with the contentClass and relevant to the locale, or an empty Set if none are found.

Parameters:

contentClass - the assignment-compatible Class of the content to be found.

locale - the locale releveant to the content to be found.

orderBy - property names in order of precedence to order results by.

Returns:

a Set of all default content that is assignment-compatible with the contentClass, or an empty Set if none are found.

Throws:

IllegalArgumentException - if contentClass is null.

IllegalStateException - if this Murq instance is closed.

getAllByClass

public Set<IContent> getAllByClass(Class contentClass,
                                   String[] orderBy)

Returns a Set of ALL content that is assignment-compatible with the contentClass and relevant to the locale, or an empty Set if none are found.

Parameters:

contentClass - the assignment-compatible Class of the content to be found.

orderBy - property names in order of precedence to order results by.

Returns:

content that is assignment-compatible with the contentClass, or an empty Set if none are found.

Throws:

IllegalArgumentException - if contentClass is null.

IllegalStateException - if this Murq instance is closed.

get

public IContent get(String contentId)

Returns the default content associated with the specified contentId, or null if no content is found.

Parameters:

contentId - id associated with the content to be returned.

Returns:

the default content associated with the specified contentId, or null if no content is found.

Throws:

IllegalArgumentException - if contentId is null.

IllegalStateException - if this Murq instance is closed.

get

public IContent get(String contentId,
                    Locale locale)

Returns the content associated with the specified contentId and relevant to the locale, or null if no content is found.

Parameters:

contentId - id associated with the content to be returned.

locale - the locale relevant to the content to be returned.

Returns:

the content associated with the specified contentId and relevant to the locale, or null if no content is found.

Throws:

IllegalArgumentException - if contentId is null.

IllegalStateException - if this Murq instance is closed.

getAll

public Set<IContent> getAll(String contentId,
                            String[] orderBy)

Returns a Set of ALL content - regardless of locale - matching the specified contentId, or an empty Set if none are found.

Parameters:

contentId - the id of the content to be found.

orderBy - property names in order or precedence to order results by.

Returns:

a Set of all content - regardless of locale - matching the specified contentId, or an empty Set if none are found.

Throws:

IllegalArgumentException - if contentClass is null.

IllegalStateException - if this Murq instance is closed.

read

public int read(String contentId,
                OutputStream out)

Reads the default binary data associated with the contentId and writes it to the specified out.

Parameters:

contentId - the identifier associated with the binary data to be read.

out - destination of the read binary data.

Returns:

number of bytes read, or -1 if none.

Throws:

IllegalArgumentException - if contentClass is null.

IllegalStateException - if this Murq instance is closed.

read

public int read(String contentId,
                Locale locale,
                OutputStream out)

Reads binary data relevant to the locale and associated with the contentId, writing it to the specified out.

Parameters:

contentId - the identifier associated with the binary data to be read.

locale - the locale relevant to the data to be returned.

out - destination of the read binary data.

Returns:

number of bytes read, or -1 if none.

Throws:

IllegalArgumentException - if contentClass is null.

IllegalStateException - if this Murq instance is closed.

put

public void put(IContent content)

Persists the specified content. This is the same as put(IContent, boolean) with a false force argument.

Parameters:

content - the content to be persisted.

Throws:

IllegalArgument - if content is null.

ConcurrentModificationException - if content already exists and is an older version than the one currently persisted.

IllegalStateException - if this Murq instance is closed.

See Also:

put(IContent, boolean)

put

public void put(IContent content,
                boolean force)

Persists the specified content, ignoring any possible concurrent modification issues if force is true.

Content is considered to be new if IContent.getContentId() returns null. In this case, a unique id will be set, both in the persisted copy and the content passed in. New content also has it's creationDate set.

All content, new or updated, has it's lastModified date updated.

Parameters:

content - the content to be persisted.

force - set to true to ignore concurent modification checks.

Throws:

IllegalArgument - if content is null.

ConcurrentModificationException - if force is false and content already exists and is an older version than the one already persisted.

IllegalStateException - if this Murq instance is closed.

write

public int write(IBinaryContent content,
                 InputStream in)

Persists the specified binary data from the in along with the metadata describing it in the content. The same as calling write(IBinaryContent, InputStream, boolean) with a false force argument.

Parameters:

content - the metadata content describing the binary data.

in - binary data to read and persist.

Returns:

the number of bytes persisted, or -1 if none.

Throws:

IllegalArgument - if content is null.

ConcurrentModificationException - if content already exists and is an older version than the one currently persisted.

IllegalStateException - if this Murq instance is closed.

See Also:

write(IBinaryContent, InputStream, boolean)

write

public int write(IBinaryContent content,
                 InputStream in,
                 boolean force)

Persists the specified binary data from the in along with the metadata describing it in the content, ignoring any possible concurrent modification issues if force is true.

Parameters:

content - the metadata content describing the binary data.

in - binary data to read and persist.

force - set to true to ignore concurent modification checks.

Throws:

IllegalArgument - if content is null.

ConcurrentModificationException - if force is false and content already exists and is an older version than the one already persisted.

IllegalStateException - if this Murq instance is closed.

removeAll

public boolean removeAll(String contentId)

Removes all content, in all locales, associated with the specified contentId.

Parameters:

contentId - id associated with the content to be removed.

Returns:

true if successful, false otherwise.

Throws:

IllegalArgumentException - if contentId is null.

IllegalStateException - if this Murq instance is closed.

remove

public boolean remove(IContent content)

Removes the specified content.

Parameters:

content - the content to be removed.

Returns:

true if successful, false otherwise.

Throws:

IllegalArgumentException - if content is null.

IllegalStateException - if this Murq instance is closed.

remove

public boolean remove(String contentId,
                      Locale locale)

Removes the specified content.

Parameters:

contentId - the id associated with the content to be removed.

locale - the locale relevant to the content to be removed.

Returns:

true if successful, false otherwise.

Throws:

IllegalArgumentException - if contentId is null.

IllegalStateException - if this Murq instance is closed.

addLink

public void addLink(String linkName,
                    String contentId)

Provides a simple name link to the specified contentId.

Parameters:

linkName - name of the link.

contentId - id to be the target of the link.

Throws:

IllegalArgumentException - if linkName or contentId is null.

IllegalStateException - if this Murq instance is closed.

removeLink

public void removeLink(String linkName)

Removes a simple name link.

Parameters:

linkName - name of the link to remove.

Throws:

IllegalArgumentException - if linkName is null.

IllegalStateException - if this Murq instance is closed.

removeLinks

public void removeLinks(String contentId)

Removes all links associated with the contentId.

Parameters:

contentId - the contentId for which all associated links should be removed.

Throws:

IllegalArgumentException - if contentId is null.

IllegalStateException - if this Murq instance is closed.

resovleLink

public IContent resovleLink(String linkName)

Returns the default IContent target of the specified linkName, or null if none exists.

Parameters:

linkName - name of the link to resolve.

Returns:

the target of the specified linkName, or null if none exists.

Throws:

IllegalArgumentException - if linkName is null.

IllegalStateException - if this Murq instance is closed.

resolveLink

public IContent resolveLink(String linkName,
                            Locale locale)

Returns the IContent relevant to the locale targeted by the specified linkName, or null if none exists.

Parameters:

linkName - name of the link to resolve.

locale - the locale relevant to content.

Returns:

the content relevant to the locale targeted by the specified linkName, or null if none exists.

Throws:

IllegalArgumentException - if linkName is null.

IllegalStateException - if this Murq instance is closed.

resolveLinkId

public String resolveLinkId(String linkName)

Returns the contentId relevant to the specified linkName, or null if none exists.

Parameters:

linkName - name of the link to resolve.

Returns:

the contentId relevant to the specified linkName, or null if none exists.

Throws:

IllegalArgumentException - if linkName is null.

IllegalStateException - if this Murq instance is closed.

getLinkNames

public Set<String> getLinkNames()

Returns all current link names.

Returns:

all current link names.

Throws:

IllegalStateException - if this Murq instance is closed.

add

public void add(ISource src)

Adds all content from the specified unencrypted src to this instance.

Warning: In the case of conflicting link names, the added link names will overwrite the existing links.

Parameters:

src - source of content to be added.

Throws:

IllegalArgumentException - if src is null.

IllegalStateException - if this Murq instance is closed.

add

public void add(ISource src,
                String password)

Adds all content from the specified src to this instance.

Warning: In the case of conflicting link names, the added link names will overwrite the existing links.

Parameters:

src - source of content to be added.

password - password required to access the src, or null if unencrypted.

Throws:

IllegalArgumentException - if src is null.

IllegalStateException - if this Murq instance is closed.

isUpdating

public boolean isUpdating()

Returns true if there are ContentEvents being processed.

Returns:

true if there are ContentEvents being processed.

toString

public String toString()

Overrides:

toString in class Object

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable