MutableDataSource (stSoftware API)

java.lang.Object
- com.aspc.DBObj.MutableDataSource

All Implemented Interfaces:

DataSource, MemoryHandler

Direct Known Subclasses:

SanityCheckDataSource, SudoDataSource
```
public class MutableDataSource
extends java.lang.Object
implements DataSource, MemoryHandler
```
MutableDataSource is the primary method of accessing the database. It holds a reference to all
modified/deleted/created DBObjects retrieved via this MutableDataSource. Validations and saving applies
to all DBObjects in the universe as a whole. MutableDataSource has to be invalidated using the dispose()
method.

All database queries and updates are subject to access control based on the login passed in the constructor.

A mutable data source is designed to be SINGLE THREADED.

Life Cycle.
1. When an DBObject is fetched from a MutableDataSource a weak reference is held on this DBObject if the same key/row is fetched the same DBObject will be returned.
2. If a DBObject is modified/touched/deleted/created it is added to the universe of the MutableDataSource that the DBObject originated from. No validation is done at this stage. If the object is created autoEnterCreate() /extAutoEnterCreate() is called, if the object is deleted then delete()/extDelete() is called, if the object is modified then eventFieldUpdated() is called.
3. The MutableDataSource has two methods validateUniverse() and save(). If save() is called without calling validateUniverse() first or the universe has been modified since the last call to validateUniverse(), validateUniverse() will be automatically called.
4. validateUniverse() calls iPreValidate()/extPreValidate()/extPreValidateDelete() for each object in the universe. The universe is then locked and iValidateRecord()/extValidateRecord()/extValidateDelete() is called for each object.
5. save() calls extPreSaveRecord()/extPreDeleteRecord() for each object in the universe. If the universe has been modified since the last validation validateUniverse() will be called. Then the universe is locked and the save process begins. During the save process and within the database transaction extSaveRecord()/extDeleteRecord() will be called. Once the transaction has completed extPostSaveRecord()/extPostDeleteRecord(). The universe is then cleared and unlocked.
6. dispose(): the function dispose() has to be called in order to properly release an instance of MutableDataSource.
  
  Usage Pattern:
  // declare the datasource MutableDataSource ds=null; try { // create a datasource ds = new MutableDataSource(...); // use the datasource ... } finally { // release the datasource inside the finally block if (ds != null) ds.dispose(); // the datasource cannot be used any longer }
Why put things in preValidate() instead of preSave() ? Well two reasons.
1. The data entry screens call validateUniverse() they expect that if validateUniverse returns no errors they can proceed with the save(). This is generally the case but if preSave() modifies the universe into an invalid state ( maybe as simple as a mandatory field missing or touching a record that was previously invalid) the save() will not proceed and you'll see Alfred.
2. The preValidate() can look at the Object and put it into a validate state eg. create a map record.
THREAD MODE: SINGLE-THREADED
Since:

January 23, 2001, 2:20 PM

Author:

Nigel Leck

Nested Class Summary
- Nested classes/interfaces inherited from interface com.aspc.remote.memory.MemoryHandler
  MemoryHandler.Cost

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ATTRIBUTE_MODE` the mode
`static java.lang.String`	`ENV_DEFAULT_VALIDATE_PARALLEL` Should the validate in parallel be enabled by default
`static java.lang.String`	`ENV_VALIDATE_PARALLEL_SIZE` the number of objects before we parallel the validate
`static java.lang.String`	`MODE_BULK_LOAD` the bulk load
`static java.lang.String`	`NEXT_NUMBER_ROWID` Next number identifier for ROWID
`static java.lang.String`	`NEXT_NUMBER_TRANSACTION` Next number identifier for TRANSACTION
`protected Login`	`sudoLogin` the login this data source was created with

Constructor Summary

Constructors
Constructor and Description
`MutableDataSource(DataSource ds)` A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.
`MutableDataSource(Login login)` A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.
`MutableDataSource(Login login, Login realLogin)` A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.
`MutableDataSource(Session session)` A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`abort()` abort the datasource and remove any locks.
`void`	`addJournalHint(DBClass dbClass, long rowUID)` add to the journal Hint
`boolean`	`changeThreadMode(ThreadCop.MODE mode)` change the thread mode for this object
`void`	`clearSavePoint(java.lang.String id)`
`DBObject`	`create(DBClass dbClass)` Creates a new DBObject of a particular type
`DBObject`	`create(DBClass dbClass, FldParams params)` Creates a new DBObject of a particular type
`DBObject`	`create(GlobalId classGid)` Creates a new DBObject of a particular type
`DBObject`	`create(java.lang.String className)` Creates a new DBObject of a particular type
`boolean`	`disableParallelValidation(boolean flag)`
`void`	`dispose()` dispose of this MutableDataSource clear to tables and make sure we can't use this MutableDataSource after calling this method THREAD SAFE: This method is designed to be safe to be called from external threads.
`DBObject`	`duplicate(DBObject orig)` Creates a new DBObject of the same class type and copies all the fields.
`void`	`excludeFromGroup(ContactGroup group)` exclude the current user from the group.
`void`	`excludeFromGroup(ContactGroup group, Person person)` exclude the contact from the group
`DBClass`	`findDBClass(GlobalId classId)` Find a DBClass by it's global id.
`DBClass`	`findDBClass(java.lang.String className)` Finds the DBClass by name THREAD SAFE: Just calling the VirtualDB version of find class which is thread safe.
`DBClassAbstract`	`findDBClassAbstract(GlobalId classId)` Find a DBClass by it's global id.
`DBClassAbstract`	`findDBClassAbstract(java.lang.String className)` Finds the DBClass by name THREAD SAFE: Just calling the VirtualDB version of find class which is thread safe.
`DBObject`	`findKey(GlobalId valueId, GlobalId classId)` Find a DBObject via it's value global ID and class global ID
`DBObject`	`findKey(GlobalId id, java.lang.String defName)` Finds a new DBObject by its value id and the class name
`DBObject`	`findKey(GlobalKey gKey)` Finds a new DBObject by its primary key THREAD SAFE: Multi-Threaded access allowed.
`DBObject`	`findKey(java.lang.String value, java.lang.String defName)` find a key
`DBObject`	`findRow(long rowId, DBClassConcrete def, Hint hint)` Finds a DBObject by it's rowId THREAD SAFE: Multi-Threaded access allowed.
`long`	`forceToDB(java.lang.String message)` Repeatedly try to write this job to the database.
`long`	`freeMemory(double percentage)` Free memory at this level and below.
`java.lang.Object`	`getAttribute(java.lang.String name)` Gets a general purpose attribute
`java.lang.Object`	`getCacheObject(java.lang.String key)` return a cached object
`MemoryHandler.Cost`	`getCost()` The cost level for this MemoryHandler.
`DataSource`	`getCurrentDataSource()` get the current datasource, if from VurtualDB then the thread local version
`VirtualDB`	`getDataBase()` Returns the VirtualDB for this MutableDataSource.
`DataSource`	`getDataBaseReadOnly()` Returns itself.
`long`	`getEstimatedSize()` The estimated size of data held by this memory handler
`Globals`	`getGlobalObject()` Get the globals object
`DBResult`	`getInwardLinkage(DBClass sourceClass, DBField sourceField, DBObject target, HintField hint)` If this is an incoming link and the base object is new then don't check the database for records as there will not/should not be any records.
`HintData`	`getJournalHint(DBClass dbClass)` get the journal hint
`long`	`getLastAccessed()` The last time this memory handle was accessed
`Login`	`getLogin()` Returns the Login for this MutableDataSource.
`DBQueryHandler`	`getQueryHandler(DBClass searchClass)` Makes a Query handler for simple virtual db.
`DataBase`	`getRawReadDB()` Deprecated.
`DataBase`	`getRawWriteDB()` Returns the physical WRITE database for this datasource
`Login`	`getRealLogin()` The real login THREAD SAFE: Multi-Threaded- We will allow Multi-Thread access to this method as it doesn't cause any real harm.
`Session`	`getSession()` Get the current session
`java.util.TimeZone`	`getTimeZone()` Returns the login which created this MutableDataSource's current timeZone.
`Person`	`getUser()` Returns the User for this MutableDataSource.
`boolean`	`hasChanged()` Have any objects in the universe been changed.
`boolean`	`hasChangedByUser()` Have any objects in the universe been changed.
`boolean`	`hasChild(DBClass mapClass, DBField parentField, DBObject parentObject, DBField childField, DBObject childObject)` does this map table contain a mapping for the parent to child.
`boolean`	`hasExcludedGroups()` are any contacts excluded ?
`boolean`	`hasSavePoint(java.lang.String id)` Do we have this save point defined ?
`void`	`iAddToUniverse(DBObject obj)` When a DBObject is modified in any way it adds itself to the MutableDataSource's universe.
`HashLongMap`	`iGetUniverseRowMap()` Returns a hash map of all row IDs -> DBObject changed in this MutableDataSource.
`boolean`	`isChangable()` can we change objects in the mutable data source.
`boolean`	`isChangedByUserDisabled()` Gets current setting for disabling changedByUser flag
`boolean`	`isDisposed()` has this data source been disposed ? THREAD SAFE: Multi-threaded
`boolean`	`isExcludeFromGroup(ContactGroup group, Person person)` is the contact excluded from the group.
`boolean`	`isInEventAction()` Are we currently processing event actions ?
`boolean`	`isInValidateUniverse()` Returns true if datasource is validating the universe.
`boolean`	`isOnChangeEventDisabled()` Gets current setting for disabling on change event
`boolean`	`isParallelValidationAllowed()` is parallel validation allowed.
`boolean`	`isSaveDisabled()` Has save been disabled ? Once save is disabled it can't be re-enabled as row ids are generated differently.
`boolean`	`isSaving()` Are we saving ? THREAD SAFE: Multi-Threaded access allowed.
`static boolean`	`isSimulatingJMS()` is simulating JMS
`void`	`iUpdateCacheKey(GlobalKey gKey, DBObject obj)` The key has changed for a new DBObject INTERNAL ONLY
`DBObject[]`	`listUniverse()` Returns a list of all DBObjects modified within the dataSource THREAD SAFE: Multi-Threaded access allowed.
`DALQuery`	`makeQuery(java.lang.String className)`
`void`	`markSavePoint(java.lang.String id)` Mark the save point which we can rollback to later.
`long`	`nextNumber(java.lang.String key)` Returns the next number for the passed key.
`long`	`nextNumber(java.lang.String key, int cacheSize)` Returns the next number for the passed key.
`long`	`panicFreeMemory()` Clear all memory.
`long`	`queuedFreeMemory(double percentage)` This method should implement the freeing of the method and maybe synchronized.
`EventMarker`	`raise(DBEvent event, DBObject base)` Adds this Event to the EventQueue.
`DBObject`	`recycleObject(DBObject obj)` If an DBObject has been returned by this MutableDataSource then return the same java object We can't return two references to the same row in the database as this may cause modifications to be missed.
`void`	`reindex()` re-index records
`void`	`resetReadChecks()` The required timezone
`void`	`rollbackTo(java.lang.String id)` Rollback to a save point
`long`	`save(java.lang.String reason)` Validates and then saves all records that have been modified/deleted/created by the MutableDataSource.
`MutableDataSource`	`setAttribute(java.lang.String name, java.lang.Object value)` Sets general purpose attributes
`void`	`setCacheObject(java.lang.String key, java.lang.Object obj)` set a cache object
`MutableDataSource`	`setDisableChangedByUser(boolean disable)` Sets flag to disable setting of changedByUser flag on updates
`void`	`setDisableOnChangeEvent(boolean disable)` Sets flag to disable setting of on change event
`MutableDataSource`	`setNoSave(boolean flag)` Changes to MutableDataSource into "no save" mode.
`void`	`setTimeZone(java.util.TimeZone tz)` The timezone
`void`	`setTransGroup(TransGroup tg)` The transaction group
`static void`	`simulateJMS(boolean flag)` simulate JMS
`static void`	`simulateLockedFieldCache(boolean flag)` simulate locked field cache
`long`	`tidyUp()` Tidy up the memory handler
`java.lang.String`	`toString()` Display the details of this datasource
`long`	`touch()` Record the time the universe was last changed.
`ValidationList`	`validateUniverse()` Validate all DBObjects that have been created/modified/deleted

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - NEXT_NUMBER_ROWID
```
public static final java.lang.String NEXT_NUMBER_ROWID
```
    Next number identifier for ROWID
    
    See Also:
    
    Constant Field Values
  - ATTRIBUTE_MODE
```
public static final java.lang.String ATTRIBUTE_MODE
```
    the mode
    
    See Also:
    
    Constant Field Values
  - MODE_BULK_LOAD
```
public static final java.lang.String MODE_BULK_LOAD
```
    the bulk load
    
    See Also:
    
    Constant Field Values
  - NEXT_NUMBER_TRANSACTION
```
public static final java.lang.String NEXT_NUMBER_TRANSACTION
```
    Next number identifier for TRANSACTION
    
    See Also:
    
    Constant Field Values
  - sudoLogin
```
protected Login sudoLogin
```
    the login this data source was created with
  - ENV_VALIDATE_PARALLEL_SIZE
```
public static final java.lang.String ENV_VALIDATE_PARALLEL_SIZE
```
    the number of objects before we parallel the validate
    
    See Also:
    
    Constant Field Values
  - ENV_DEFAULT_VALIDATE_PARALLEL
```
public static final java.lang.String ENV_DEFAULT_VALIDATE_PARALLEL
```
    Should the validate in parallel be enabled by default
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - MutableDataSource
```
public MutableDataSource(@Nonnull
                         Login login)
```
    A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.
    
    Parameters:
    
    login - The user's login.
  - MutableDataSource
```
public MutableDataSource(@Nonnull
                         Login login,
                         @Nullable
                         Login realLogin)
```
    A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.
    
    Parameters:
    
    realLogin - The real login ( sudo)
    
    login - The user's login.
  - MutableDataSource
```
public MutableDataSource(@Nonnull
                         Session session)
```
    A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.
    
    Parameters:
    
    session - the current session
  - MutableDataSource
```
public MutableDataSource(@Nonnull
                         DataSource ds)
```
    A valid login is required to create a mutableDataSource All database requests will be limited by the ACLs associated with Login's access group.
    
    Parameters:
    
    ds - A datasource to source the login and timezone
- Method Detail
  - disableParallelValidation
```
public boolean disableParallelValidation(boolean flag)
```
  - isParallelValidationAllowed
```
@CheckReturnValue
public boolean isParallelValidationAllowed()
```
    is parallel validation allowed.
    
    Returns:
    
    true if allowed.
  - addJournalHint
```
public void addJournalHint(@Nonnull
                           DBClass dbClass,
                           long rowUID)
```
    add to the journal Hint
    
    Parameters:
    
    dbClass - the class
    
    rowUID - the row UID
  - getJournalHint
```
@CheckReturnValue
 @Nullable
public HintData getJournalHint(@Nonnull
                                                            DBClass dbClass)
```
    get the journal hint
    
    Parameters:
    
    dbClass - the class
    
    Returns:
    
    the hint if any.
  - simulateLockedFieldCache
```
public static void simulateLockedFieldCache(boolean flag)
```
    simulate locked field cache
    
    Parameters:
    
    flag - true to turn on.
  - simulateJMS
```
public static void simulateJMS(boolean flag)
```
    simulate JMS
    
    Parameters:
    
    flag - true to turn on.
  - isSimulatingJMS
```
@CheckReturnValue
public static boolean isSimulatingJMS()
```
    is simulating JMS
    
    Returns:
    
    true if simulating
  - changeThreadMode
```
public boolean changeThreadMode(@Nonnull
                                ThreadCop.MODE mode)
```
    change the thread mode for this object
    
    Parameters:
    
    mode - new mode
    
    Returns:
    
    always true just so you can call from assert
  - getSession
```
@CheckReturnValue
 @Nullable
public Session getSession()
```
    Get the current session
    
    Specified by:
    
    getSession in interface DataSource
    
    Returns:
    
    the session
  - hasChild
```
@CheckReturnValue
public boolean hasChild(@Nonnull
                                          DBClass mapClass,
                                          @Nonnull
                                          DBField parentField,
                                          @Nonnull
                                          DBObject parentObject,
                                          @Nonnull
                                          DBField childField,
                                          @Nonnull
                                          DBObject childObject)
                                   throws java.lang.Exception
```
    does this map table contain a mapping for the parent to child.
    
    Specified by:
    
    hasChild in interface DataSource
    
    Parameters:
    
    mapClass - The map class
    
    parentField - the parent link
    
    parentObject - the parent object
    
    childField - the child link
    
    childObject - the child object
    
    Returns:
    
    TRUE if a mapping found
    
    Throws:
    
    java.lang.Exception - a serious problem.
  - getCurrentDataSource
```
@Nonnull
 @CheckReturnValue
public DataSource getCurrentDataSource()
```
    get the current datasource, if from VurtualDB then the thread local version
    
    Specified by:
    
    getCurrentDataSource in interface DataSource
    
    Returns:
    
    the current data source
  - isDisposed
```
@CheckReturnValue
public boolean isDisposed()
```
    has this data source been disposed ? THREAD SAFE: Multi-threaded
    
    Returns:
    
    true if it has.
  - abort
```
public void abort()
```
    abort the datasource and remove any locks. THREAD SAFE: Multi-threaded
  - dispose
```
public void dispose()
```
    dispose of this MutableDataSource clear to tables and make sure we can't use this MutableDataSource after calling this method THREAD SAFE: This method is designed to be safe to be called from external threads. PROCESS CANCEL
  - getGlobalObject
```
@CheckReturnValue
 @Nonnull
public Globals getGlobalObject()
                                                    throws java.lang.Exception
```
    Get the globals object
    
    Specified by:
    
    getGlobalObject in interface DataSource
    
    Returns:
    
    The Global Object
    
    Throws:
    
    java.lang.Exception - A serious problem
  - setNoSave
```
@Nonnull
public MutableDataSource setNoSave(boolean flag)
```
    Changes to MutableDataSource into "no save" mode. If we know the data source will never be saved then we can make some internal optimizations.
    
    Parameters:
    
    flag - Turn no save on.
    
    Returns:
    
    this
  - isSaveDisabled
```
@CheckReturnValue
public boolean isSaveDisabled()
```
    Has save been disabled ? Once save is disabled it can't be re-enabled as row ids are generated differently. Also we can bypass createAccess checks. We need to do this for the Search screens.
    
    Returns:
    
    true if save has been disabled.
  - nextNumber
```
@CheckReturnValue
public long nextNumber(@Nonnull
                                         java.lang.String key)
```
    Returns the next number for the passed key.
    
    A default cache size of ten will be used.
    
    Specified by:
    
    nextNumber in interface DataSource
    
    Parameters:
    
    key - The next number key
    
    Returns:
    
    The next number.
  - nextNumber
```
@CheckReturnValue
public long nextNumber(@Nonnull
                                         java.lang.String key,
                                         int cacheSize)
```
    Returns the next number for the passed key.
    
    When the MutableDataSource is in "no save" mode we can make pseudo unique numbers by reserving 0xf0000000 for memory generated next numbers.
    
    Specified by:
    
    nextNumber in interface DataSource
    
    Parameters:
    
    key - The next number key
    
    cacheSize - The number of additional numbers to book. Disabled by zero, default if -1
    
    Returns:
    
    The next number
  - isInValidateUniverse
```
@CheckReturnValue
public boolean isInValidateUniverse()
```
    Returns true if datasource is validating the universe.
    
    Returns:
    
    Boolean
  - isChangable
```
@CheckReturnValue
public boolean isChangable()
```
    can we change objects in the mutable data source.
    
    Returns:
    
    true if can change.
  - isInEventAction
```
@CheckReturnValue
public boolean isInEventAction()
```
    Are we currently processing event actions ?
    
    Returns:
    
    true if processing.
  - getInwardLinkage
```
@Nonnull
 @CheckReturnValue
public DBResult getInwardLinkage(@Nonnull
                                                             DBClass sourceClass,
                                                             @Nonnull
                                                             DBField sourceField,
                                                             @Nullable
                                                             DBObject target,
                                                             @Nullable
                                                             HintField hint)
                                                      throws java.lang.Exception
```
    If this is an incoming link and the base object is new then don't check the database for records as there will not/should not be any records. If there is then they are records in error or the base record will have a duplicate key error when you try to save it.
    
    Specified by:
    
    getInwardLinkage in interface DataSource
    
    Parameters:
    
    hint - the list of other records we will fetch
    
    sourceClass - The source class
    
    sourceField - The field that points to the target's class
    
    target - The actual DBObject that the source field points to.
    
    Returns:
    
    The record set.
    
    Throws:
    
    java.lang.Exception - A serious problem
  - touch
```
public long touch()
```
    Record the time the universe was last changed. MT FIXED: deadlock found on 16 Apr 2003. Removed Synchronized
    
    Returns:
    
    the last touched time
  - hasChanged
```
@CheckReturnValue
public boolean hasChanged()
```
    Have any objects in the universe been changed.
    
    Returns:
    
    true if changed.
  - hasChangedByUser
```
@CheckReturnValue
public boolean hasChangedByUser()
```
    Have any objects in the universe been changed.
    
    Returns:
    
    true if changed by the user
  - reindex
```
public void reindex()
             throws java.lang.Exception
```
    re-index records
    
    Throws:
    
    java.lang.Exception - A serious problem
  - hasSavePoint
```
@CheckReturnValue
public boolean hasSavePoint(@Nonnull
                                              java.lang.String id)
```
    Do we have this save point defined ?
    
    Parameters:
    
    id - The save-point to check
    
    Returns:
    
    true if we have this save-point
  - clearSavePoint
```
public void clearSavePoint(@Nonnull
                           java.lang.String id)
```
  - markSavePoint
```
public void markSavePoint(@Nonnull
                          java.lang.String id)
```
    Mark the save point which we can rollback to later.
    
    Parameters:
    
    id - the save point id
  - rollbackTo
```
public void rollbackTo(@Nonnull
                       java.lang.String id)
                throws NoSavePointException
```
    Rollback to a save point
    
    Parameters:
    
    id - save point id
    
    Throws:
    
    NoSavePointException - No save point found for this id
  - save
```
public long save(@Nonnull
                 java.lang.String reason)
          throws java.lang.Exception
```
    Validates and then saves all records that have been modified/deleted/created by the MutableDataSource.
    - Object pre-validate
    - Event validations
    - Event actions
    - Object validations
    - Pre save
    - Save
    - post save
    TODO: Transaction nr to have a cache size again.
    Parameters:
    
    reason - The reason for saving these records
    
    Returns:
    
    The transaction number
    
    Throws:
    
    java.lang.Exception - A serious problem
  - setDisableOnChangeEvent
```
public void setDisableOnChangeEvent(boolean disable)
```
    Sets flag to disable setting of on change event
    
    Parameters:
    
    disable - - if true, disabled on change event
  - isOnChangeEventDisabled
```
@CheckReturnValue
public boolean isOnChangeEventDisabled()
```
    Gets current setting for disabling on change event
    
    Returns:
    
    true if disabled.
  - setDisableChangedByUser
```
@Nonnull
public MutableDataSource setDisableChangedByUser(boolean disable)
```
    Sets flag to disable setting of changedByUser flag on updates
    
    Parameters:
    
    disable - - if true, disabled changed by user setting
    
    Returns:
    
    this
  - isChangedByUserDisabled
```
@CheckReturnValue
public boolean isChangedByUserDisabled()
```
    Gets current setting for disabling changedByUser flag
    
    Returns:
    
    true if disabled.
  - setAttribute
```
@Nonnull
public MutableDataSource setAttribute(@Nonnull
                                               java.lang.String name,
                                               @Nonnull
                                               java.lang.Object value)
```
    Sets general purpose attributes
    
    Parameters:
    
    name - The name of the attribute
    
    value - the value of the attribute
    
    Returns:
    
    this
  - excludeFromGroup
```
public void excludeFromGroup(@Nonnull
                             ContactGroup group)
```
    exclude the current user from the group.
    
    Parameters:
    
    group - the group that the user is to be excluded
  - excludeFromGroup
```
public void excludeFromGroup(@Nonnull
                             ContactGroup group,
                             @Nullable
                             Person person)
```
    exclude the contact from the group
    
    Parameters:
    
    person - the person to excluded.
    
    group - the group to have the contact excluded from
  - isExcludeFromGroup
```
@CheckReturnValue
public boolean isExcludeFromGroup(@Nonnull
                                                    ContactGroup group,
                                                    @Nonnull
                                                    Person person)
```
    is the contact excluded from the group.
    
    Specified by:
    
    isExcludeFromGroup in interface DataSource
    
    Parameters:
    
    person - the person to check.
    
    group - the group to check if the contact is excluded.
    
    Returns:
    
    true if excluded.
  - hasExcludedGroups
```
@CheckReturnValue
public boolean hasExcludedGroups()
```
    are any contacts excluded ?
    
    Specified by:
    
    hasExcludedGroups in interface DataSource
    
    Returns:
    
    true if any contacts are excluded.
  - getAttribute
```
@CheckReturnValue
 @Nullable
public java.lang.Object getAttribute(@Nonnull
                                                                  java.lang.String name)
```
    Gets a general purpose attribute
    
    Specified by:
    
    getAttribute in interface DataSource
    
    Parameters:
    
    name - the name of the attribute
    
    Returns:
    
    the value of the attribute
  - isSaving
```
@CheckReturnValue
public boolean isSaving()
```
    Are we saving ? THREAD SAFE: Multi-Threaded access allowed.
    
    Returns:
    
    true if saving
  - validateUniverse
```
@CheckReturnValue
 @Nonnull
public ValidationList validateUniverse()
                                                            throws java.lang.Exception
```
    Validate all DBObjects that have been created/modified/deleted
    
    Returns:
    
    The list of warnings/errors.
    
    Throws:
    
    java.lang.Exception - A serious problem
  - raise
```
@Nonnull
public EventMarker raise(@Nonnull
                                  DBEvent event,
                                  @Nonnull
                                  DBObject base)
                           throws java.lang.Exception
```
    Adds this Event to the EventQueue.
    
    Parameters:
    
    event - the event that is to be raised
    
    base - Base object that we are raising the Event for
    
    Returns:
    
    The DBEventQueue object if the event was added to the queue
    
    Throws:
    
    java.lang.Exception - Exception
  - iAddToUniverse
```
public void iAddToUniverse(@Nonnull
                           DBObject obj)
```
    When a DBObject is modified in any way it adds itself to the MutableDataSource's universe.
    
    INTERNAL ONLY
    
    Parameters:
    
    obj - The object to add.
  - listUniverse
```
@CheckReturnValue
 @Nonnull
public DBObject[] listUniverse()
```
    Returns a list of all DBObjects modified within the dataSource THREAD SAFE: Multi-Threaded access allowed.
    
    Returns:
    
    The list of modified DBObjects
  - getDataBase
```
@CheckReturnValue
 @Nonnull
public VirtualDB getDataBase()
```
    Returns the VirtualDB for this MutableDataSource.
    
    Specified by:
    
    getDataBase in interface DataSource
    
    Returns:
    
    The VirtualDB.
  - getDataBaseReadOnly
```
@Nonnull
 @CheckReturnValue
public DataSource getDataBaseReadOnly()
```
    Returns itself.
    
    Specified by:
    
    getDataBaseReadOnly in interface DataSource
    
    Returns:
    
    MutableDataSource.
  - getRawWriteDB
```
@Nonnull
 @CheckReturnValue
public DataBase getRawWriteDB()
                                                   throws java.sql.SQLException
```
    Returns the physical WRITE database for this datasource
    
    Returns:
    
    The physical database.
    
    Throws:
    
    java.sql.SQLException - a serious problem
  - getRawReadDB
```
@Nonnull
 @CheckReturnValue
 @Deprecated
public DataBase getRawReadDB()
                                                               throws java.sql.SQLException
```
    Deprecated.
    
    Returns the physical READ database for this datasource
    
    Returns:
    
    The physical database.
    
    Throws:
    
    java.sql.SQLException - a serious problem
  - getLogin
```
@Nonnull
 @CheckReturnValue
public Login getLogin()
```
    Returns the Login for this MutableDataSource. THREAD SAFE: Multi-Threaded- We will allow Multi-Thread access to this method as it doesn't cause any real harm.
    
    Specified by:
    
    getLogin in interface DataSource
    
    Returns:
    
    The login.
  - getRealLogin
```
@Nonnull
 @CheckReturnValue
public Login getRealLogin()
```
    The real login THREAD SAFE: Multi-Threaded- We will allow Multi-Thread access to this method as it doesn't cause any real harm.
    
    Specified by:
    
    getRealLogin in interface DataSource
    
    Returns:
    
    The login
  - getUser
```
@CheckReturnValue
 @Nullable
public Person getUser()
```
    Returns the User for this MutableDataSource.
    
    Specified by:
    
    getUser in interface DataSource
    
    Returns:
    
    The user.
  - getTimeZone
```
@Nonnull
 @CheckReturnValue
public java.util.TimeZone getTimeZone()
```
    Returns the login which created this MutableDataSource's current timeZone. THREAD SAFE: We will allow Multi-Thread access to this method as it doesn't cause any real harm.
    
    Specified by:
    
    getTimeZone in interface DataSource
    
    Returns:
    
    The TimeZone
  - setTimeZone
```
public final void setTimeZone(@Nonnull
                              java.util.TimeZone tz)
```
    The timezone
    
    Parameters:
    
    tz - the timezone
  - setTransGroup
```
public void setTransGroup(@Nullable
                          TransGroup tg)
```
    The transaction group
    
    Parameters:
    
    tg - the TransGroup
  - findDBClass
```
@Nonnull
 @CheckReturnValue
public DBClass findDBClass(@Nonnull
                                                       java.lang.String className)
                                                throws NotFoundException
```
    Finds the DBClass by name THREAD SAFE: Just calling the VirtualDB version of find class which is thread safe. .
    
    Specified by:
    
    findDBClass in interface DataSource
    
    Parameters:
    
    className - The class name to find.
    
    Returns:
    
    The DBClass
    
    Throws:
    
    NotFoundException - The class name doesn't exist
  - findDBClass
```
@Nonnull
 @CheckReturnValue
public DBClass findDBClass(@Nonnull
                                                       GlobalId classId)
                                                throws NotFoundException
```
    Find a DBClass by it's global id. THREAD SAFE: Just calling the VirtualDB version of find class which is thread safe. .
    
    Specified by:
    
    findDBClass in interface DataSource
    
    Parameters:
    
    classId - The class's global id.
    
    Returns:
    
    The DBClass
    
    Throws:
    
    NotFoundException - The class was not found.
  - findDBClassAbstract
```
@Nonnull
 @CheckReturnValue
public DBClassAbstract findDBClassAbstract(@Nonnull
                                                                       java.lang.String className)
                                                                throws NotFoundException
```
    Finds the DBClass by name THREAD SAFE: Just calling the VirtualDB version of find class which is thread safe. .
    
    Specified by:
    
    findDBClassAbstract in interface DataSource
    
    Parameters:
    
    className - The class name to find.
    
    Returns:
    
    The DBClass
    
    Throws:
    
    NotFoundException - The class name doesn't exist
  - findDBClassAbstract
```
@Nonnull
 @CheckReturnValue
public DBClassAbstract findDBClassAbstract(@Nonnull
                                                                       GlobalId classId)
                                                                throws NotFoundException
```
    Find a DBClass by it's global id.
    
    Specified by:
    
    findDBClassAbstract in interface DataSource
    
    Parameters:
    
    classId - The class's global id.
    
    Returns:
    
    The DBClass
    
    Throws:
    
    NotFoundException - The class was not found.
  - findKey
```
@Nonnull
 @CheckReturnValue
public DBObject findKey(@Nonnull
                                                    GlobalId valueId,
                                                    @Nonnull
                                                    GlobalId classId)
                                             throws NotFoundException
```
    Find a DBObject via it's value global ID and class global ID
    
    Specified by:
    
    findKey in interface DataSource
    
    Parameters:
    
    valueId - The value id
    
    classId - The class id
    
    Returns:
    
    the DBObject
    
    Throws:
    
    NotFoundException - The DBObject wasn't found
  - findKey
```
@Nonnull
 @CheckReturnValue
public DBObject findKey(@Nonnull
                                                    GlobalId id,
                                                    @Nonnull
                                                    java.lang.String defName)
                                             throws NotFoundException
```
    Finds a new DBObject by its value id and the class name
    
    Specified by:
    
    findKey in interface DataSource
    
    Parameters:
    
    id - The value id
    
    defName - The class name
    
    Returns:
    
    The DBObject
    
    Throws:
    
    NotFoundException - The DBObject wasn't found
  - findKey
```
@Nonnull
 @CheckReturnValue
public DBObject findKey(@Nonnull
                                                    GlobalKey gKey)
                                             throws NotFoundException
```
    Finds a new DBObject by its primary key THREAD SAFE: Multi-Threaded access allowed.
    
    Specified by:
    
    findKey in interface DataSource
    
    Parameters:
    
    gKey - The global key
    
    Returns:
    
    The DBObject
    
    Throws:
    
    NotFoundException - The DBObject wasn't found
  - findKey
```
@Nonnull
 @CheckReturnValue
public DBObject findKey(@Nonnull
                                                    java.lang.String value,
                                                    @Nonnull
                                                    java.lang.String defName)
                                             throws NotFoundException,
                                                    TooManyRowsException,
                                                    java.lang.Exception
```
    find a key
    
    Specified by:
    
    findKey in interface DataSource
    
    Parameters:
    
    value - the key value to search for
    
    defName - the class name to search
    
    Returns:
    
    the object found
    
    Throws:
    
    NotFoundException - The object wasn't found
    
    TooManyRowsException - many objects found
    
    java.lang.Exception - A serious problem.
  - findRow
```
@Nonnull
 @CheckReturnValue
public DBObject findRow(long rowId,
                                                    @Nonnull
                                                    DBClassConcrete def,
                                                    @Nullable
                                                    Hint hint)
                                             throws NotFoundException
```
    Finds a DBObject by it's rowId THREAD SAFE: Multi-Threaded access allowed.
    
    Specified by:
    
    findRow in interface DataSource
    
    Parameters:
    
    hint - The hint of other rows to be fetched
    
    rowId - The row id
    
    def - The DBClass
    
    Returns:
    
    The DBObject
    
    Throws:
    
    NotFoundException - The row wasn't found
  - create
```
@Nonnull
public DBObject create(@Nonnull
                                java.lang.String className)
                         throws java.lang.Exception
```
    Creates a new DBObject of a particular type
    
    Specified by:
    
    create in interface DataSource
    
    Parameters:
    
    className - The class Name
    
    Returns:
    
    The created DBObject
    
    Throws:
    
    java.lang.Exception - A serious problem occurred
  - create
```
@Nonnull
public DBObject create(@Nonnull
                                DBClass dbClass)
                         throws java.lang.Exception
```
    Creates a new DBObject of a particular type
    
    Specified by:
    
    create in interface DataSource
    
    Parameters:
    
    dbClass - The class
    
    Returns:
    
    The created DBObject
    
    Throws:
    
    java.lang.Exception - A serious problem occurred
  - create
```
@Nonnull
public DBObject create(@Nonnull
                                DBClass dbClass,
                                @Nullable
                                FldParams params)
                         throws java.lang.Exception
```
    Creates a new DBObject of a particular type
    
    Parameters:
    
    dbClass - The class
    
    params - the parameters
    
    Returns:
    
    The created DBObject
    
    Throws:
    
    java.lang.Exception - A serious problem occurred
  - create
```
@Nonnull
public DBObject create(@Nonnull
                                GlobalId classGid)
                         throws java.lang.Exception
```
    Creates a new DBObject of a particular type
    
    Specified by:
    
    create in interface DataSource
    
    Parameters:
    
    classGid - The class id
    
    Returns:
    
    The created DBObject
    
    Throws:
    
    java.lang.Exception - A serious problem occurred
  - duplicate
```
@Nonnull
public DBObject duplicate(@Nonnull
                                   DBObject orig)
                            throws java.lang.Exception
```
    Creates a new DBObject of the same class type and copies all the fields.
    
    Parameters:
    
    orig - The original DBObject to copy
    
    Returns:
    
    The duplicated DBObject
    
    Throws:
    
    java.lang.Exception - A serious problem
  - iGetUniverseRowMap
```
@CheckReturnValue
 @Nonnull
public HashLongMap iGetUniverseRowMap()
```
    Returns a hash map of all row IDs -> DBObject changed in this MutableDataSource. This is used with the DBquery for performance reasons. as the MutableDataSource may cache the HashMap. Internal use only. THREAD SAFE: Multi-Threaded access allowed.
    
    Returns:
    
    the Hash map of all row IDs changed in this MutableDataSource
  - resetReadChecks
```
public void resetReadChecks()
```
    The required timezone
  - recycleObject
```
@Nullable
public DBObject recycleObject(@Nullable
                                        DBObject obj)
                                 throws java.lang.Exception
```
    If an DBObject has been returned by this MutableDataSource then return the same java object We can't return two references to the same row in the database as this may cause modifications to be missed.
    
    Parameters:
    
    obj - The object to recycle
    
    Returns:
    
    The recycled object
    
    Throws:
    
    java.lang.Exception - A serious problem
  - iUpdateCacheKey
```
public void iUpdateCacheKey(@Nonnull
                            GlobalKey gKey,
                            @Nonnull
                            DBObject obj)
```
    The key has changed for a new DBObject
    
    INTERNAL ONLY
    
    Parameters:
    
    gKey - the key updated.
    
    obj - The object that we are talking about.
  - getQueryHandler
```
@Nonnull
 @CheckReturnValue
public DBQueryHandler getQueryHandler(@Nonnull
                                                                  DBClass searchClass)
```
    Makes a Query handler for simple virtual db. depending of Data Source type the optimal method of performing the database queries differs. THREAD SAFE: Multi-Threaded access allowed.
    
    Specified by:
    
    getQueryHandler in interface DataSource
    
    Parameters:
    
    searchClass - the class that is being searched.
    
    Returns:
    
    the query handler.
  - setCacheObject
```
public void setCacheObject(@Nonnull
                           java.lang.String key,
                           @Nonnull
                           java.lang.Object obj)
```
    set a cache object
    
    Specified by:
    
    setCacheObject in interface DataSource
    
    Parameters:
    
    key - The cache key
    
    obj - The cached value
  - getCacheObject
```
@CheckReturnValue
 @Nullable
public java.lang.Object getCacheObject(@Nonnull
                                                                    java.lang.String key)
```
    return a cached object
    
    Specified by:
    
    getCacheObject in interface DataSource
    
    Parameters:
    
    key - the cache key
    
    Returns:
    
    the cached value
  - forceToDB
```
public long forceToDB(@Nonnull
                      java.lang.String message)
               throws java.lang.Exception
```
    Repeatedly try to write this job to the database. Database concurrency We loop on dirty cache exceptions where to force the write to the database.
    
    Parameters:
    
    message - The save message
    
    Returns:
    
    The transaction number
    
    Throws:
    
    java.lang.Exception - A serious problem
  - toString
```
@Nonnull
 @CheckReturnValue
public java.lang.String toString()
```
    Display the details of this datasource
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string.
  - makeQuery
```
@Nonnull
 @CheckReturnValue
public DALQuery makeQuery(@Nonnull
                                                      java.lang.String className)
```
  - getCost
```
@Nonnull
 @CheckReturnValue
public MemoryHandler.Cost getCost()
```
    Description copied from interface: MemoryHandler
    
    The cost level for this MemoryHandler.
    
    Specified by:
    
    getCost in interface MemoryHandler
    
    Returns:
    
    The cost
  - freeMemory
```
@Nonnegative
public long freeMemory(double percentage)
```
    Description copied from interface: MemoryHandler
    
    Free memory at this level and below.
    To prevent a possible deadlock this method should not be synchronized. It should call MemoryManager.callFreeMemory which in turn calls queuedFreeMemory()
    
    Specified by:
    
    freeMemory in interface MemoryHandler
    
    Parameters:
    
    percentage - to be freed
    
    Returns:
    
    the approximate amount freed
  - tidyUp
```
@Nonnegative
public long tidyUp()
```
    Description copied from interface: MemoryHandler
    
    Tidy up the memory handler
    
    Specified by:
    
    tidyUp in interface MemoryHandler
    
    Returns:
    
    the total bytes cleared.
  - queuedFreeMemory
```
@Nonnegative
public long queuedFreeMemory(double percentage)
```
    Description copied from interface: MemoryHandler
    
    This method should implement the freeing of the method and maybe synchronized.
    
    Specified by:
    
    queuedFreeMemory in interface MemoryHandler
    
    Parameters:
    
    percentage - The percentage to be cleared.
    
    Returns:
    
    the estimated amount cleared.
  - panicFreeMemory
```
@Nonnegative
public long panicFreeMemory()
```
    Description copied from interface: MemoryHandler
    
    Clear all memory.
    
    Specified by:
    
    panicFreeMemory in interface MemoryHandler
    
    Returns:
    
    the estimated amount cleared.
  - getEstimatedSize
```
@CheckReturnValue
 @Nonnegative
public long getEstimatedSize()
```
    Description copied from interface: MemoryHandler
    
    The estimated size of data held by this memory handler
    
    Specified by:
    
    getEstimatedSize in interface MemoryHandler
    
    Returns:
    
    The estimated number of bytes held.
  - getLastAccessed
```
@CheckReturnValue
 @Nonnegative
public long getLastAccessed()
```
    Description copied from interface: MemoryHandler
    
    The last time this memory handle was accessed
    
    Specified by:
    
    getLastAccessed in interface MemoryHandler
    
    Returns:
    
    The last time in seconds this memory handler was accessed.

Class MutableDataSource

Life Cycle.

Nested Class Summary

Nested classes/interfaces inherited from interface com.aspc.remote.memory.MemoryHandler

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NEXT_NUMBER_ROWID

ATTRIBUTE_MODE

MODE_BULK_LOAD

NEXT_NUMBER_TRANSACTION

sudoLogin

ENV_VALIDATE_PARALLEL_SIZE

ENV_DEFAULT_VALIDATE_PARALLEL

Constructor Detail

MutableDataSource

MutableDataSource

MutableDataSource

MutableDataSource

Method Detail

disableParallelValidation

isParallelValidationAllowed

addJournalHint

getJournalHint

simulateLockedFieldCache

simulateJMS

isSimulatingJMS

changeThreadMode

getSession

hasChild

getCurrentDataSource

isDisposed

abort

dispose

getGlobalObject

setNoSave

isSaveDisabled

nextNumber

nextNumber

isInValidateUniverse

isChangable

isInEventAction

getInwardLinkage

touch

hasChanged

hasChangedByUser

reindex

hasSavePoint

clearSavePoint

markSavePoint

rollbackTo

save

setDisableOnChangeEvent

isOnChangeEventDisabled

setDisableChangedByUser

isChangedByUserDisabled

setAttribute

excludeFromGroup

excludeFromGroup

isExcludeFromGroup

hasExcludedGroups

getAttribute

isSaving

validateUniverse

raise

iAddToUniverse

listUniverse

getDataBase

getDataBaseReadOnly

getRawWriteDB

getRawReadDB

getLogin

getRealLogin

getUser

getTimeZone

setTimeZone

setTransGroup

findDBClass