story.dbcore.admin
Class DBCoreInterface

java.lang.Object
  extended by story.dbcore.admin.DBCoreInterface

public final class DBCoreInterface
extends java.lang.Object

Point of entry for db-core data and functionality. All classes that need either must go through a DBCoreInterface.

The only classes that are exposed by DBCoreInterface (or by one of the classes it exposes) are RelatedNodes, NodeAddress, LinkSet, NodeInstancing, QueryResultSet, QueryResult and Via, and pointers to protected classes (such as DocumentID and NodeAddress). These classes are all read-only (with the exception of QueryResultSet). Everything else, such as Document, NodeRepository and LinkRepository, is hidden and should never be instantiated by a high-level class.


Constructor Summary
DBCoreInterface(RepositoryFactoryInterface repositoryFactory, NodeFactoryInterface nodeFactory, LinkProperties linkProperties, SymbolTable symbolTable, AppName applicationName, AppFileExtension applicationFileExtension)
          Constructor
 
Method Summary
 CommandSequence closeCommandBuffer()
          Turn off command buffering.
 CommandReturn execute(Command command)
          Interpret and execute a command.
 void execute(CommandSequence sequence)
          Execute all the commands in a CommandSequence.
 void execute(Executable executable)
           
 AppFileExtension getAppFileExtension()
          Return the application file extension
 AppName getAppName()
          Retrieve the application name.
 HistoryFrameID getCurrentStateID()
          Gets the HistoryFrameID of the history frame on the top of the undo stack, i.e., the current state of the system.
 int getHistoryFrameRelationship(HistoryFrameID frame)
          Determine the placement of a particular history frame.
 Command getLastCommand()
          Returns the Command of the last command issued to the DBCore, or an exception if this is the first command
 java.util.Iterator getNodeAttributeIDs(NodeAddress node)
          Return an iterator over all the AttributeIDs of a node's attributes.
 DocumentID getOpenDocument()
          Return the ID of the currently open document, or DocumentID.NO_DOCUMENT if no document is currently open.
 Executable getRedoableOperation()
          Returns the CommandType of the command associated with the subsequent recent state-changing operation in the redo stack.
 RepositoryFactoryInterface getRepositoryFactory()
          Retrieve the RepositoryFactory
 SymbolTable getSymbolTable()
          Retrieve the symbol table.
 Executable getUndoableOperation()
          Returns the CommandType of the command associated with the most recent state-changing operation, i.e., the operation at the top of the undo stack.
 void openCommandBuffer()
          Turn on command buffering.
 void reset()
           
 void setRevalidateInstanceNodes(boolean revalidates)
          This turns intance node validation on or off.
 void setStatelessMode(boolean statelessMode)
          Turn Stateless Mode on or off.
 void setSymbolTable(SymbolTable st)
          Set the symbol table.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DBCoreInterface

public DBCoreInterface(RepositoryFactoryInterface repositoryFactory,
                       NodeFactoryInterface nodeFactory,
                       LinkProperties linkProperties,
                       SymbolTable symbolTable,
                       AppName applicationName,
                       AppFileExtension applicationFileExtension)
Constructor

Method Detail

getAppName

public AppName getAppName()
Retrieve the application name.


getAppFileExtension

public AppFileExtension getAppFileExtension()
Return the application file extension


getSymbolTable

public SymbolTable getSymbolTable()
Retrieve the symbol table.


getRepositoryFactory

public RepositoryFactoryInterface getRepositoryFactory()
Retrieve the RepositoryFactory


setSymbolTable

public void setSymbolTable(SymbolTable st)
Set the symbol table.


execute

public void execute(Executable executable)
             throws Scheherexception
Throws:
Scheherexception

execute

public void execute(CommandSequence sequence)
             throws Scheherexception
Execute all the commands in a CommandSequence. In case of an error in any command, the system state is reconstructed to the state that existed prior to the start of execution.

The commands in the sequence are treated atomically. That is, there is only one frame pushed onto the undo stack. That, in turn, means that you won't be able to undo a part of the sequence -- you can undo none of it or all of it.

Throws:
Scheherexception

execute

public CommandReturn execute(Command command)
                      throws Scheherexception
Interpret and execute a command. Each command has a set of parameters but this function tries to be helpful rather than strict. For example, if you pass a string where an ID of some kind is required, it will instantiate a new ID for you. If you pass a string where a NodeAddress is required, it will quickly search for and retrieve the node with that name (or throw and error if it does not exist).

Warning: If command buffering is on (ie., openCommandBuffer() has been run), commands will be added to the command buffer and not run, and this function will always return a NonExecutedCommandReturn object.

TODO: document all supported commands. Until that's done, assume it's the same as in the javadoc for Document, with the exception that the first argument must be a CommandType object.

Throws:
Scheherexception

getHistoryFrameRelationship

public int getHistoryFrameRelationship(HistoryFrameID frame)
                                throws Scheherexception
Determine the placement of a particular history frame.

Returns 0 if the frame represents the current state of the system, -1 if the frame is in the undo stack, 1 if the frame is in the redo stack.

Throws an UnrelatedHistoryFrame exception if the frame is none of these.

Throws:
Scheherexception

getUndoableOperation

public Executable getUndoableOperation()
Returns the CommandType of the command associated with the most recent state-changing operation, i.e., the operation at the top of the undo stack. If there is nothing to undo, returns null.


getRedoableOperation

public Executable getRedoableOperation()
Returns the CommandType of the command associated with the subsequent recent state-changing operation in the redo stack. If there is nothing to undo, returns null.


getCurrentStateID

public HistoryFrameID getCurrentStateID()
Gets the HistoryFrameID of the history frame on the top of the undo stack, i.e., the current state of the system. Exposed to the "public" in case they need to track how much the system has changed. A HistoryFrameID of value 0 means the system is in its startup (empty) state.


getOpenDocument

public DocumentID getOpenDocument()
Return the ID of the currently open document, or DocumentID.NO_DOCUMENT if no document is currently open.


getLastCommand

public Command getLastCommand()
                       throws Scheherexception
Returns the Command of the last command issued to the DBCore, or an exception if this is the first command

Throws:
Scheherexception

getNodeAttributeIDs

public java.util.Iterator getNodeAttributeIDs(NodeAddress node)
                                       throws Scheherexception
Return an iterator over all the AttributeIDs of a node's attributes.

Throws:
Scheherexception

setStatelessMode

public void setStatelessMode(boolean statelessMode)
                      throws Scheherexception
Turn Stateless Mode on or off. Defaultis off. In Stateless Mode, DBCore will NOT maintain the undo and redo stacks. Trying to undo commands executed while in Stateless Mode (even if you are not in SM when you try to undo) will result in a fatal error. SM also disables error recovery; in case of error, DBCore will terminate, not restore the database to the last good state.

Use Stateless Mode to reduce memory requirements when building extremely large graphs by avoiding an undo stack that is redundant to the graph itself.

Throws:
Scheherexception

setRevalidateInstanceNodes

public void setRevalidateInstanceNodes(boolean revalidates)
This turns intance node validation on or off. If on (default), instance nodes and LinkInstancings are revalidated after each state-changing operation. For example, if an node with an expansion parameter of "take some other node with two children" is instantiated, but then the "other node" gets a third child, the system throws an error that the instance node's definition is no longer valid.

Because node and attribute inference allow nodes to affect other nodes far away on the graph, the only sure-fire way I could think of to guarantee that all instance nodes remain valid is to check all instance nodes after every state-changing operation. Unfortunately, this is very slow then there are hundreds of instance nodes. It is possible to alleviate the problem by grouping commands to DBCore into CommandSequences (with validation only checked at the end of the sequence). But if a higher-level app is sure that it is not issuing commands to DBCore that invalidate previously created instance nodes, or does not want this case, to throw an error, it can disable the checking. This will significantly improve performance.

Note that even if validation is disabled, the system will still throw an error if a node is removed that another node instances (via InstanceOf) or uses in its definition (via InstanceWith arcs).


openCommandBuffer

public void openCommandBuffer()
                       throws Scheherexception
Turn on command buffering. In this case, any commands sent to execute() will be buffered rather than executed.

Throws:
Scheherexception

closeCommandBuffer

public CommandSequence closeCommandBuffer()
Turn off command buffering. Subsequent Commands sent to execute() will be executed immediately. Note that this does not execute any commands in the command buffer; it only returns them.


reset

public void reset()


Copyright © 2011 David K. Elson. All Rights Reserved.