things.universe
Interface Universe

All Known Implementing Classes:
UniverseLocal

public interface Universe

Universe interface.

Version:
1.0

Version History

 EPG - Adapted from another project - 16 MAY 04
 EPG - Add Make-Local concept - 2 SEP 06
 
Author:
Erich P. Gatejen

Field Summary
static java.lang.String CONFIG_CLEARANCE
           
static java.lang.String CONFIG_LIST
           
static java.lang.String CONFIG_NAME
           
static java.lang.String CONFIG_PATH
           
static java.lang.String CONFIG_ROOT
           
static java.lang.String CONFIG_TYPE
           
static java.lang.String CONFIG_TYPE_LOCAL
           
 
Method Summary
 void delete(java.lang.String... name)
          Delete an object.
 void deleteByKey(java.lang.String key)
          Delete an object by Key.
 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.
 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 for this operation only.
 

Field Detail

CONFIG_PATH

static final java.lang.String CONFIG_PATH
See Also:
Constant Field Values

CONFIG_LIST

static final java.lang.String CONFIG_LIST
See Also:
Constant Field Values

CONFIG_ROOT

static final java.lang.String CONFIG_ROOT
See Also:
Constant Field Values

CONFIG_TYPE

static final java.lang.String CONFIG_TYPE
See Also:
Constant Field Values

CONFIG_TYPE_LOCAL

static final java.lang.String CONFIG_TYPE_LOCAL
See Also:
Constant Field Values

CONFIG_NAME

static final java.lang.String CONFIG_NAME
See Also:
Constant Field Values

CONFIG_CLEARANCE

static final java.lang.String CONFIG_CLEARANCE
See Also:
Constant Field Values
Method Detail

getId

UniverseID getId()
                 throws UniverseException
Get the id for this universe.

Returns:
the Id.
Throws:
UniverseException
See Also:
UniverseID

getValidatedName

java.lang.String getValidatedName(java.lang.String... name)
                                  throws UniverseException
Get a validated name for the object. This is valid for this universe ONLY.

Parameters:
name - universe object name (path components will be appended).
Returns:
the validated name as a single string.
Throws:
UniverseException

getObjectAccessor

Accessor getObjectAccessor(java.lang.String... name)
                           throws UniverseException
Get an object accessor for the named object. This is valid for this universe ONLY.

Parameters:
name - universe object name (path components will be appended).
Returns:
the validated name as a single string.
Throws:
UniverseException

getStream

java.io.InputStream getStream(java.lang.String... name)
                              throws UniverseException
Get an InputStream that can read from the universe object

Parameters:
name - universe object name (path components will be appended).
Returns:
a stream to the object
Throws:
UniverseException

getStreamByKey

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.

Parameters:
key - a valid key for the object
Returns:
a stream to the object
Throws:
UniverseException

putStream

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.

Parameters:
name - universe object name (path components will be appended).
Returns:
a stream to the object
Throws:
UniverseException

putStreamByKey

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.

Parameters:
key - a valid key for the object
Returns:
a stream to the object
Throws:
UniverseException

putStreamAppender

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.

Parameters:
name - universe object name (path components will be appended).
Returns:
a stream to the object
Throws:
UniverseException

putStreamAppenderByKey

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.

Parameters:
key - a valid key for the object
Returns:
a stream to the object
Throws:
UniverseException

reserveUnique

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.

Parameters:
base - base path for the object (including root object name)
Returns:
name of the reserved unique object.
Throws:
UniverseException

lock

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 using the named item.

Parameters:
name - universe object name (path components will be appended).
Returns:
a key that can be used to unlock it.
Throws:
UniverseException

unlock

boolean unlock(java.lang.String key)
               throws UniverseException
Unlock an object using a key for this operation only. If the key doesn't unlock anything, nothing bad will happen (other than return false).

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

boolean isLocked(java.lang.String... name)
                 throws UniverseException
Check to see if the object is locked

Parameters:
name - universe object name (name components will be appended).
Returns:
true if the object is locked, otherwise false
Throws:
UniverseException

makeLocal

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.

Parameters:
name - universe object name (path components will be appended).
Returns:
a File
Throws:
UniverseException

releaseLocal

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.

Parameters:
theLocalFile - the file. If nonsensical, it will quietly return.
Throws:
UniverseException

exists

boolean exists(java.lang.String... name)
               throws UniverseException
Check to see if an object exists

Parameters:
name - universe object name (path components will be appended).
Returns:
true if the object exists, otherwise false
Throws:
UniverseException

delete

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.

Parameters:
name - universe object name (path components will be appended).
Throws:
UniverseException

deleteByKey

void deleteByKey(java.lang.String key)
                 throws UniverseException
Delete an object by Key. This will unlock the object so the delete can occur for this operation only. If the key is bad, it will throw an exception.

Parameters:
key - a key that can unlock it
Throws:
UniverseException

size

long size(java.lang.String... name)
          throws UniverseException
Report the size object from the universe in bytes.

Parameters:
name - universe object name (path components will be appended).
Returns:
the size or 0 if empty
Throws:
UniverseException

lastModifiedDate

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.

Parameters:
name - universe object name (path components will be appended).
Returns:
milliseconds from epoch time.
Throws:
UniverseException

match

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.

Parameters:
name - universe object name, partial name, and/or path (path components will be appended)
Returns:
all the matches.
Throws:
UniverseException

feature

java.lang.String feature(java.lang.String name,
                         ThingsPropertyView params)
                         throws UniverseException
Activate a feature by name.

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

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.

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

finalizeUniverse

void finalizeUniverse()
                      throws UniverseException
This will always be called when the universe is accessor is destroyed. You should not call this directly.

Throws:
UniverseException


Things.