things.universe.server
Class UniverseLocal

java.lang.Object
  things.universe.server.UniverseLocal

All Implemented Interfaces:

Universe

public class UniverseLocal
extends java.lang.Object
implements Universe

Universe local. Relative paths are NEVER allowed.

There are some places where lock races could occur. For this simple server, it isn't much of a deal. If they become a problem, I'll fix them later. It's mostly the time between a lock is checked and the operation is actually done, like in delete.

CONFIGS:
CONFIG_PATH "path" = root path to universe

Version:

1.0

Version History

   EPG - New - 2 JUL 04
 EPG - Add multi-Strings.  It's a bit messy now - 10 AUG 06 
 

Author:

Erich P. Gatejen

Field Summary

Fields inherited from interface things.universe.Universe

CONFIG_CLEARANCE, CONFIG_LIST, CONFIG_NAME, CONFIG_PATH, CONFIG_ROOT, CONFIG_TYPE, CONFIG_TYPE_LOCAL

Constructor Summary

UniverseLocal()

Method Summary

void	delete(java.lang.String... name) Delete an object.
void	deleteByKey(java.lang.String key) Delete an object.
boolean	exists(java.lang.String... name) Check to see if an object exists
java.lang.String	feature(java.lang.String name, ThingsPropertyView params) Activate a feature by name.
java.lang.String	featureByKey(java.lang.String key, ThingsPropertyView params) Activate a feature by name.
void	finalizeUniverse() This will always be called when the universe is accessor is destroyed.
void	genesis(java.lang.String path, UniverseID uid) This will always be called when the universe server is created.
UniverseID	getId() Get the id for this universe.
Accessor	getObjectAccessor(java.lang.String... name) Get an object accessor for the named object.
java.io.InputStream	getStream(java.lang.String... name) Get an InputStream that can read from the universe object
java.io.InputStream	getStreamByKey(java.lang.String key) Get an InputStream that can read from the universe object.
java.lang.String	getValidatedName(java.lang.String... name) Get a validated name for the object.
boolean	isLocked(java.lang.String... name) Check to see if the object is locked.
long	lastModifiedDate(java.lang.String... name) Get the last modified date in milliseconds from epoch time.
java.lang.String	lock(java.lang.String... name) Lock an object.
java.io.File	makeLocal(java.lang.String... name) Make a local reference or copy of the object in a FILE.
java.util.Collection<java.lang.String>	match(java.lang.String... name) Get all the object names that match the path.
java.io.OutputStream	putStream(java.lang.String... name) Get an OutputStream that can write to the universe object.
java.io.OutputStream	putStreamAppender(java.lang.String... name) Get an OutputStream that can write to the universe object.
java.io.OutputStream	putStreamAppenderByKey(java.lang.String key) Get an OutputStream that can write to the universe object.
java.io.OutputStream	putStreamByKey(java.lang.String key) Get an OutputStream that can write to the universe object.
void	releaseLocal(java.io.File theLocalFile) Release a local reference or copy of the object in a FILE.
java.lang.String	reserveUnique(java.lang.String base) Reserve unique object in the universe.
long	size(java.lang.String... name) Report the size object from the universe in bytes.
boolean	unlock(java.lang.String key) Unlock an object using a key.

Methods inherited from class java.lang.Object

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

Constructor Detail

UniverseLocal

public UniverseLocal()

Method Detail

getId

public UniverseID getId()
                 throws UniverseException

Get the id for this universe.

Specified by:

getId in interface Universe

Returns:

the Id.

Throws:

UniverseException

See Also:

UniverseID

getValidatedName

public java.lang.String getValidatedName(java.lang.String... name)
                                  throws UniverseException

Get a validated name for the object. This is valid for this universe ONLY.

Specified by:

getValidatedName in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

the validated name as a single string.

Throws:

UniverseException

getObjectAccessor

public Accessor getObjectAccessor(java.lang.String... name)
                           throws UniverseException

Get an object accessor for the named object. This is valid for this universe ONLY.

Specified by:

getObjectAccessor in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

the validated name as a single string.

Throws:

UniverseException

getStream

public java.io.InputStream getStream(java.lang.String... name)
                              throws UniverseException

Get an InputStream that can read from the universe object

Specified by:

getStream in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

a stream to the object

Throws:

UniverseException

getStreamByKey

public java.io.InputStream getStreamByKey(java.lang.String key)
                                   throws UniverseException

Get an InputStream that can read from the universe object. This will unlock the object so the write can occur. If the key is bad, it will throw an exception.

Specified by:

getStreamByKey in interface Universe

Parameters:

key - a valid key for the object

Returns:

a stream to the object

Throws:

UniverseException

putStream

public java.io.OutputStream putStream(java.lang.String... name)
                               throws UniverseException

Get an OutputStream that can write to the universe object. If will replace the object if one is already there.

Specified by:

putStream in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

a stream to the object

Throws:

UniverseException

putStreamByKey

public java.io.OutputStream putStreamByKey(java.lang.String key)
                                    throws UniverseException

Get an OutputStream that can write to the universe object. If will replace the object if one is already there. This will unlock the object so the write can occur. If the key is bad, it will throw an exception.

Specified by:

putStreamByKey in interface Universe

Parameters:

key - a valid key for the object

Returns:

a stream to the object

Throws:

UniverseException

putStreamAppender

public java.io.OutputStream putStreamAppender(java.lang.String... name)
                                       throws UniverseException

Get an OutputStream that can write to the universe object. If will append to the object if one is already there, otherwise it will create a new one.

Specified by:

putStreamAppender in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

a stream to the object

Throws:

UniverseException

putStreamAppenderByKey

public java.io.OutputStream putStreamAppenderByKey(java.lang.String key)
                                            throws UniverseException

Get an OutputStream that can write to the universe object. If will append to the object if one is already there, otherwise it will create a new one. This will unlock the object so the write can occur for this operation only. If the key is bad, it will throw an exception.

Specified by:

putStreamAppenderByKey in interface Universe

Parameters:

key - a valid key for the object

Returns:

a stream to the object

Throws:

UniverseException

reserveUnique

public java.lang.String reserveUnique(java.lang.String base)
                               throws UniverseException

Reserve unique object in the universe. Guarantee it is a unique instance of it. Great for temp objects.

Specified by:

reserveUnique in interface Universe

Parameters:

base - base path for the object (including root object name)

Returns:

name of the reserved unique object.

Throws:

UniverseException

lock

public java.lang.String lock(java.lang.String... name)
                      throws UniverseException

Lock an object. This is blocking. It will return a key that can be used to unlock it. Locks will prevent anyone from getting new access to an object. However, if something is already access an object, a new lock will not effect it.

Specified by:

lock in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

a key that can be used to unlock it.

Throws:

UniverseException

unlock

public boolean unlock(java.lang.String key)
               throws UniverseException

Unlock an object using a key. If the key doesn't unlock anything, nothing bad will happen (other than return false).

Specified by:

unlock in interface Universe

Parameters:

key - a key that can unlock it

Returns:

true if the object was found and unlocked, false if no matching key

Throws:

UniverseException

isLocked

public boolean isLocked(java.lang.String... name)
                 throws UniverseException

Check to see if the object is locked. It'll throw an exception if the name is null.

Specified by:

isLocked in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

true if the object is locked, otherwise false

Throws:

UniverseException

makeLocal

public java.io.File makeLocal(java.lang.String... name)
                       throws UniverseException

Make a local reference or copy of the object in a FILE. The reference will be good until you release it. It will persist past system shutdown, so if you don't release it, they can build up. If the object may or may not be directly modified by the File--assume either case. However, when released, it will allow modifications the original with the local copy (if it wasn't already). Note the word "allow," it will not account for any unflushed data or dangling references. So, be sure the local usage is DONE and flushed before releasing.

This will lock the object until released. No other operations will be allowed.

This could be a good way to subvert security, if the implementation allows it. It is up to the implementation to keep the world safe from local files.

Specified by:

makeLocal in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

a File

Throws:

UniverseException

releaseLocal

public void releaseLocal(java.io.File theLocalFile)
                  throws UniverseException

Release a local reference or copy of the object in a FILE. The original object will resemble the local.

Specified by:

releaseLocal in interface Universe

Parameters:

theLocalFile - the file. If nonsensical, it will quietly return.

Throws:

UniverseException

exists

public boolean exists(java.lang.String... name)
               throws UniverseException

Check to see if an object exists

Specified by:

exists in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

true if the object exists, otherwise false

Throws:

UniverseException

delete

public void delete(java.lang.String... name)
            throws UniverseException

Delete an object. If the object has open streams, it will quietly fail. It will not schedule it for later deletion. It's up to you to verify and destroy it later. If the object is locked, you'll get an exception.

Specified by:

delete in interface Universe

Parameters:

name - universe object name (path components will be appended).

Throws:

UniverseException

deleteByKey

public void deleteByKey(java.lang.String key)
                 throws UniverseException

Delete an object. If the object has open streams, it will quietly fail. It will not schedule it for later deletion. It's up to you to verify and destroy it later. This will unlock the object and delete it. If the key is bad, it will throw an exception.

Specified by:

deleteByKey in interface Universe

Parameters:

key - a key that can unlock it

Throws:

UniverseException

size

public long size(java.lang.String... name)
          throws UniverseException

Report the size object from the universe in bytes. It will throw a UniverseException if the object doesn't exist or cannot be accessed.

Specified by:

size in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

the size or 0 if empty

Throws:

UniverseException

lastModifiedDate

public long lastModifiedDate(java.lang.String... name)
                      throws UniverseException

Get the last modified date in milliseconds from epoch time. It will throw an exception if it can't find it.

Specified by:

lastModifiedDate in interface Universe

Parameters:

name - universe object name (path components will be appended).

Returns:

milliseconds from epoch time.

Throws:

UniverseException

match

public java.util.Collection<java.lang.String> match(java.lang.String... name)
                                             throws UniverseException

Get all the object names that match the path. No wildcards are necessary. The final path element will treated as a substring of all matches, if it doesn't match a path completely. If it does match a path completely, all elements under that path (in the one ply only) will be given.

Specified by:

match in interface Universe

Parameters:

name - universe object name, partial name, and/or path (path components will be appended)

Returns:

all the matches.

Throws:

UniverseException

feature

public java.lang.String feature(java.lang.String name,
                                ThingsPropertyView params)
                         throws UniverseException

Activate a feature by name.

Specified by:

feature in interface Universe

Parameters:

name - name of the feature

params - parameters for the feature expressed as a view

Returns:

a response from the feature as a String

Throws:

UniverseException

See Also:

ThingsPropertyView

featureByKey

public java.lang.String featureByKey(java.lang.String key,
                                     ThingsPropertyView params)
                              throws UniverseException

Activate a feature by name. This will unlock the object so the feature can occur for this operation only. If the key is bad, it will throw an exception.

Specified by:

featureByKey in interface Universe

Parameters:

key - key to the object

params - parameters for the feature expressed as a view

Returns:

a response from the feature as a String

Throws:

UniverseException

See Also:

ThingsPropertyView

genesis

public void genesis(java.lang.String path,
                    UniverseID uid)
             throws UniverseException

This will always be called when the universe server is created. You should not call this directly.

Parameters:

path - immutable path to the root

uid - immutable id

Throws:

UniverseException

See Also:

UniverseID

finalizeUniverse

public void finalizeUniverse()
                      throws UniverseException

This will always be called when the universe is accessor is destroyed. You should not call this directly.

Specified by:

finalizeUniverse in interface Universe

Throws:

UniverseException