things.universe.server
Class UniverseLocal

java.lang.Object
  extended by 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


Things.