DataDomain (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.access, class: DataDomain

# Class DataDomain

java.lang.Object
org.apache.cayenne.access.DataDomain

All Implemented Interfaces:
  `DataChannel`

public class DataDomain extends Object implements DataChannel
DataDomain performs query routing functions in Cayenne. DataDomain creates single data source abstraction hiding multiple physical data sources from the user. When a child DataContext sends a query to the DataDomain, it is transparently routed to an appropriate DataNode.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected DataRowStoreFactory`
  `dataRowStoreFactory`
  `protected DataNode`
  `defaultNode`
  `protected EntityResolver`
  `entityResolver`
  `protected EntitySorter`
  `entitySorter`
  `protected EventManager`
  `eventManager`
  `protected DataDomainFlushActionFactory`
  `flushActionFactory`
  `protected JdbcEventLogger`
  `jdbcEventLogger`
  `protected int`
  `maxIdQualifierSize`
  `protected String`
  `name`
  `protected Map<String,DataNode>`
  `nodes`
  `protected Map<String,DataNode>`
  `nodesByDataMapName`
  `protected AdhocObjectFactory`
  `objectFactory`
  `protected Map<String,String>`
  `properties`
  `protected QueryCache`
  `queryCache`
  `protected List<DataChannelQueryFilter>`
  `queryFilters`
  `static final boolean`
  `SHARED_CACHE_ENABLED_DEFAULT`
  `static final String`
  `SHARED_CACHE_ENABLED_PROPERTY`
  `protected boolean`
  `sharedCacheEnabled`
  `protected DataRowStore`
  `sharedSnapshotCache`
  `protected boolean`
  `stopped`
  `protected List<DataChannelSyncFilter>`
  `syncFilters`
  `protected TransactionManager`
  `transactionManager`
  `static final boolean`
  `VALIDATING_OBJECTS_ON_COMMIT_DEFAULT`
  `static final String`
  `VALIDATING_OBJECTS_ON_COMMIT_PROPERTY`
  `protected boolean`
  `validatingObjectsOnCommit`

  ### Fields inherited from interface DataChannel

  `FLUSH_CASCADE_SYNC, FLUSH_NOCASCADE_SYNC, GRAPH_CHANGED_SUBJECT, GRAPH_FLUSHED_SUBJECT, GRAPH_ROLLEDBACK_SUBJECT, ROLLBACK_CASCADE_SYNC`
  Modifier and Type
  Field
  Description
  `static final int`
  `FLUSH_CASCADE_SYNC`
  A synchronization type that results in changes from an ObjectContext to be recorded in the parent DataChannel.
  `static final int`
  `FLUSH_NOCASCADE_SYNC`
  A synchronization type that results in changes from an ObjectContext to be recorded in the parent DataChannel.
  `static final EventSubject`
  `GRAPH_CHANGED_SUBJECT`
  `static final EventSubject`
  `GRAPH_FLUSHED_SUBJECT`
  `static final EventSubject`
  `GRAPH_ROLLEDBACK_SUBJECT`
  `static final int`
  `ROLLBACK_CASCADE_SYNC`
  A synchronization type that results in cascading rollback of changes through the DataChannel stack.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataDomain(String name)`
  Creates a DataDomain and assigns it a name.
  `DataDomain(String name, Map<String,String> properties)`
  Deprecated.
  since 4.0 unused

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDataMap(DataMap dataMap)`
  `void`
  `addListener(Object listener)`
  Adds a listener, mapping its methods to events based on annotations.
  `void`
  `addNode(DataNode node)`
  Adds new DataNode.
  `void`
  `addQueryFilter(DataChannelQueryFilter filter)`
  Adds a new query filter.
  `void`
  `addSyncFilter(DataChannelSyncFilter filter)`
  Adds a new sync filter.
  `protected void`
  `checkStopped()`
  Checks that Domain is not stopped.
  `DataMap`
  `getDataMap(String mapName)`
  `Collection<DataMap>`
  `getDataMaps()`
  Returns a collection of registered DataMaps.
  `DataNode`
  `getDataNode(String nodeName)`
  Returns registered DataNode whose name matches `name` parameter.
  `Collection<DataNode>`
  `getDataNodes()`
  Returns an unmodifiable collection of DataNodes associated with this domain.
  `DataRowStoreFactory`
  `getDataRowStoreFactory()`
  `DataNode`
  `getDefaultNode()`
  An optional DataNode that is used for DataMaps that are not linked to a DataNode explicitly.
  `EntityResolver`
  `getEntityResolver()`
  Returns an EntityResolver that stores mapping information for this domain.
  `EntitySorter`
  `getEntitySorter()`
  `EventManager`
  `getEventManager()`
  Returns EventManager used by this DataDomain.
  `int`
  `getMaxIdQualifierSize()`
  Returns a maximum number of object IDs to match in a single query for queries that select objects based on collection of ObjectIds.
  `String`
  `getName()`
  Returns "name" property value.
  `Map<String,String>`
  `getProperties()`
  `QueryCache`
  `getQueryCache()`
  Returns shared `QueryCache` used by this DataDomain.
  `List<DataChannelQueryFilter>`
  `getQueryFilters()`
  Returns an unmodifiable list of query filters registered with this DataDomain.
  `DataRowStore`
  `getSharedSnapshotCache()`
  Returns snapshots cache for this DataDomain, lazily initializing it on the first call if 'sharedCacheEnabled' flag is true.
  `List<DataChannelSyncFilter>`
  `getSyncFilters()`
  Returns an unmodifiable list of sync filters registered with this DataDomain.
  `void`
  `initWithProperties(Map<String,String> properties)`
  Deprecated.
  since 4.0 properties are processed by the DI provider.
  `boolean`
  `isSharedCacheEnabled()`
  Returns `true` if DataContexts produced by this DataDomain are using shared DataRowStore.
  `boolean`
  `isValidatingObjectsOnCommit()`
  Returns whether child DataContexts default behavior is to perform object validation before commit is executed.
  `DataNode`
  `lookupDataNode(DataMap map)`
  Returns a DataNode that should handle queries for all entities in a DataMap.
  `QueryResponse`
  `onQuery(ObjectContext originatingContext, Query query)`
  Runs query returning generic QueryResponse.
  `GraphDiff`
  `onSync(ObjectContext originatingContext, GraphDiff changes, int syncType)`
  Only handles commit-type synchronization, ignoring any other type.
  `void`
  `performQueries(Collection<? extends Query> queries, OperationObserver callback)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  use `onQuery(ObjectContext, Query)` instead.
  `void`
  `removeDataMap(String mapName)`
  Removes named DataMap from this DataDomain and any underlying DataNodes that include it.
  `void`
  `removeDataNode(String nodeName)`
  Removes a DataNode from DataDomain.
  `void`
  `removeQueryFilter(DataChannelQueryFilter filter)`
  Removes a query filter from the filter chain.
  `void`
  `removeSyncFilter(DataChannelSyncFilter filter)`
  Removes a sync filter from the filter chain.
  `protected void`
  `resetProperties()`
  `void`
  `setDataRowStoreFactory(DataRowStoreFactory dataRowStoreFactory)`
  `void`
  `setDefaultNode(DataNode defaultNode)`
  `void`
  `setEntityResolver(EntityResolver entityResolver)`
  Sets EntityResolver.
  `void`
  `setEntitySorter(EntitySorter entitySorter)`
  `void`
  `setEventManager(EventManager eventManager)`
  Sets EventManager used by this DataDomain.
  `void`
  `setMaxIdQualifierSize(int maxIdQualifierSize)`
  `void`
  `setName(String name)`
  Sets "name" property to a new value.
  `void`
  `setQueryCache(QueryCache queryCache)`
  `void`
  `setSharedCacheEnabled(boolean sharedCacheEnabled)`
  `void`
  `setSharedSnapshotCache(DataRowStore snapshotCache)`
  Shuts down the previous cache instance, sets cache to the new DataSowStore instance and updates two properties of the new DataSowStore: name and eventManager.
  `void`
  `setValidatingObjectsOnCommit(boolean flag)`
  Sets the property defining whether child DataContexts should perform object validation before commit is executed.
  `void`
  `shutdown()`
  Shutdowns all owned data nodes and marks this domain as stopped.
  `String`
  `toString()`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### SHARED_CACHE_ENABLED_PROPERTY

    public static final String SHARED_CACHE_ENABLED_PROPERTY
    See Also:
      - Constant Field Values

  - ### SHARED_CACHE_ENABLED_DEFAULT

    public static final boolean SHARED_CACHE_ENABLED_DEFAULT
    See Also:
      - Constant Field Values

  - ### VALIDATING_OBJECTS_ON_COMMIT_PROPERTY

    public static final String VALIDATING_OBJECTS_ON_COMMIT_PROPERTY
    See Also:
      - Constant Field Values

  - ### VALIDATING_OBJECTS_ON_COMMIT_DEFAULT

    public static final boolean VALIDATING_OBJECTS_ON_COMMIT_DEFAULT
    See Also:
      - Constant Field Values

  - ### jdbcEventLogger

    protected JdbcEventLogger jdbcEventLogger
    Since:
      3.1

  - ### transactionManager

    protected TransactionManager transactionManager
    Since:
      4.0

  - ### dataRowStoreFactory

    protected DataRowStoreFactory dataRowStoreFactory
    Since:
      4.0

  - ### maxIdQualifierSize

    protected int maxIdQualifierSize
    Since:
      3.1

  - ### queryFilters

    protected List<DataChannelQueryFilter> queryFilters
    Since:
      4.1

  - ### syncFilters

    protected List<DataChannelSyncFilter> syncFilters
    Since:
      4.1

  - ### flushActionFactory

    protected DataDomainFlushActionFactory flushActionFactory
    Since:
      4.2

  - ### objectFactory

    protected AdhocObjectFactory objectFactory
    Since:
      4.2

  - ### nodes

    protected Map<String,DataNode> nodes

  - ### nodesByDataMapName

    protected Map<String,DataNode> nodesByDataMapName

  - ### defaultNode

    protected DataNode defaultNode

  - ### properties

    protected Map<String,String> properties

  - ### entityResolver

    protected EntityResolver entityResolver

  - ### sharedSnapshotCache

    protected DataRowStore sharedSnapshotCache

  - ### name

    protected String name

  - ### queryCache

    protected QueryCache queryCache

  - ### sharedCacheEnabled

    protected boolean sharedCacheEnabled

  - ### validatingObjectsOnCommit

    protected boolean validatingObjectsOnCommit

  - ### eventManager

    protected EventManager eventManager
    Since:
      1.2

  - ### entitySorter

    protected EntitySorter entitySorter
    Since:
      1.2

  - ### stopped

    protected boolean stopped

- ## Constructor Details

  - ### DataDomain

    public DataDomain(String name)
    Creates a DataDomain and assigns it a name.

  - ### DataDomain

    @Deprecated public DataDomain(String name, Map<String,String> properties)
    Deprecated.
    since 4.0 unused
    Creates new DataDomain.
    Parameters:
      `name` - DataDomain name. Domain can be located using its name in the Configuration object.
      `properties` - A Map containing domain configuration properties.

- ## Method Details

  - ### checkStopped

    protected void checkStopped() throws DomainStoppedException
    Checks that Domain is not stopped. Throws DomainStoppedException otherwise.
    Throws:
      `DomainStoppedException`
    Since:
      3.0

  - ### getEntitySorter

    public EntitySorter getEntitySorter()
    Since:
      3.1

  - ### setEntitySorter

    public void setEntitySorter(EntitySorter entitySorter)
    Since:
      3.1

  - ### resetProperties

    protected void resetProperties()
    Since:
      1.1

  - ### initWithProperties

    @Deprecated public void initWithProperties(Map<String,String> properties)
    Deprecated.
    since 4.0 properties are processed by the DI provider.
    Reinitializes domain state with a new set of properties.
    Since:
      1.1

  - ### getEventManager

    public EventManager getEventManager()
    Returns EventManager used by this DataDomain.
    Specified by:
      `getEventManager` in interface `DataChannel`
    Since:
      1.2

  - ### setEventManager

    public void setEventManager(EventManager eventManager)
    Sets EventManager used by this DataDomain.
    Since:
      1.2

  - ### getName

    public String getName()
    Returns "name" property value.

  - ### setName

    public void setName(String name)
    Sets "name" property to a new value.

  - ### isSharedCacheEnabled

    public boolean isSharedCacheEnabled()
    Returns `true` if DataContexts produced by this DataDomain are using shared DataRowStore. Returns `false` if each DataContext would work with its own DataRowStore. Note that this setting can be overwritten per DataContext.

  - ### setSharedCacheEnabled

    public void setSharedCacheEnabled(boolean sharedCacheEnabled)

  - ### isValidatingObjectsOnCommit

    public boolean isValidatingObjectsOnCommit()
    Returns whether child DataContexts default behavior is to perform object validation before commit is executed.
    Since:
      1.1

  - ### setValidatingObjectsOnCommit

    public void setValidatingObjectsOnCommit(boolean flag)
    Sets the property defining whether child DataContexts should perform object validation before commit is executed.
    Since:
      1.1

  - ### getProperties

    public Map<String,String> getProperties()
    Returns:
      a Map of properties for this DataDomain.
    Since:
      1.1

  - ### getSharedSnapshotCache

    public DataRowStore getSharedSnapshotCache()
    Returns snapshots cache for this DataDomain, lazily initializing it on the first call if 'sharedCacheEnabled' flag is true.

  - ### setSharedSnapshotCache

    public void setSharedSnapshotCache(DataRowStore snapshotCache)
    Shuts down the previous cache instance, sets cache to the new DataSowStore instance and updates two properties of the new DataSowStore: name and eventManager.

  - ### addDataMap

    public void addDataMap(DataMap dataMap)

  - ### getDataMap

    public DataMap getDataMap(String mapName)
    Since:
      3.1

  - ### removeDataMap

    public void removeDataMap(String mapName)
    Removes named DataMap from this DataDomain and any underlying DataNodes that include it.
    Since:
      3.1

  - ### removeDataNode

    public void removeDataNode(String nodeName)
    Removes a DataNode from DataDomain. Any maps previously associated with this node within domain will still be kept around, however they wan't be mapped to any node.

  - ### getDataMaps

    public Collection<DataMap> getDataMaps()
    Returns a collection of registered DataMaps.

  - ### getDataNodes

    public Collection<DataNode> getDataNodes()
    Returns an unmodifiable collection of DataNodes associated with this domain.

  - ### addNode

    public void addNode(DataNode node)
    Adds new DataNode.

  - ### getDataNode

    public DataNode getDataNode(String nodeName)
    Returns registered DataNode whose name matches `name` parameter.
    Since:
      3.1

  - ### lookupDataNode

    public DataNode lookupDataNode(DataMap map)
    Returns a DataNode that should handle queries for all entities in a DataMap.
    Since:
      1.1

  - ### setEntityResolver

    public void setEntityResolver(EntityResolver entityResolver)
    Sets EntityResolver. If not set explicitly, DataDomain creates a default EntityResolver internally on demand.
    Since:
      1.1

  - ### shutdown

    @BeforeScopeEnd public void shutdown()
    Shutdowns all owned data nodes and marks this domain as stopped.

  - ### performQueries

    @Deprecated(since="5.0", forRemoval=true) public void performQueries(Collection<? extends Query> queries, OperationObserver callback)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use `onQuery(ObjectContext, Query)` instead.
    Routes queries to appropriate DataNodes for execution

  - ### onQuery

    public QueryResponse onQuery(ObjectContext originatingContext, Query query)
    Runs query returning generic QueryResponse.
    Specified by:
      `onQuery` in interface `DataChannel`
    Parameters:
      `originatingContext` - an ObjectContext that originated the query, used to register result objects.
    Returns:
      a generic response object that encapsulates result of the execution.
    Since:
      1.2

  - ### getEntityResolver

    public EntityResolver getEntityResolver()
    Returns an EntityResolver that stores mapping information for this domain.
    Specified by:
      `getEntityResolver` in interface `DataChannel`

  - ### onSync

    public GraphDiff onSync(ObjectContext originatingContext, GraphDiff changes, int syncType)
    Only handles commit-type synchronization, ignoring any other type.
    Specified by:
      `onSync` in interface `DataChannel`
    Parameters:
      `originatingContext` - an ObjectContext that initiated the sync. Can be null.
      `changes` - diff from the context that initiated the sync.
      `syncType` - One of `DataChannel.FLUSH_NOCASCADE_SYNC`, `DataChannel.FLUSH_CASCADE_SYNC`, `DataChannel.ROLLBACK_CASCADE_SYNC`.
    Since:
      1.2

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### getQueryCache

    public QueryCache getQueryCache()
    Returns shared `QueryCache` used by this DataDomain.
    Since:
      3.0

  - ### setQueryCache

    public void setQueryCache(QueryCache queryCache)

  - ### getDataRowStoreFactory

    public DataRowStoreFactory getDataRowStoreFactory()
    Since:
      4.0

  - ### setDataRowStoreFactory

    public void setDataRowStoreFactory(DataRowStoreFactory dataRowStoreFactory)
    Since:
      4.0

  - ### getQueryFilters

    public List<DataChannelQueryFilter> getQueryFilters()
    Returns an unmodifiable list of query filters registered with this DataDomain.

    Filter ordering note: filters are applied in reverse order of their occurrence in the filter list. I.e. the last filter in the list called first in the chain.

    Since:
      4.1

  - ### getSyncFilters

    public List<DataChannelSyncFilter> getSyncFilters()
    Returns an unmodifiable list of sync filters registered with this DataDomain.

    Filter ordering note: filters are applied in reverse order of their occurrence in the filter list. I.e. the last filter in the list called first in the chain.

    Since:
      4.1

  - ### addQueryFilter

    public void addQueryFilter(DataChannelQueryFilter filter)
    Adds a new query filter. Also registers passed filter as an event listener, if any of its methods have event annotations.
    Since:
      4.1

  - ### addSyncFilter

    public void addSyncFilter(DataChannelSyncFilter filter)
    Adds a new sync filter. Also registers passed filter as an event listener, if any of its methods have event annotations.
    Since:
      4.1

  - ### removeQueryFilter

    public void removeQueryFilter(DataChannelQueryFilter filter)
    Removes a query filter from the filter chain.
    Since:
      4.1

  - ### removeSyncFilter

    public void removeSyncFilter(DataChannelSyncFilter filter)
    Removes a sync filter from the filter chain.
    Since:
      4.1

  - ### addListener

    public void addListener(Object listener)
    Adds a listener, mapping its methods to events based on annotations. This is a shortcut for 'getEntityResolver().getCallbackRegistry().addListener(listener)'.
    Since:
      4.0

  - ### getDefaultNode

    public DataNode getDefaultNode()
    An optional DataNode that is used for DataMaps that are not linked to a DataNode explicitly.
    Since:
      3.1

  - ### setDefaultNode

    public void setDefaultNode(DataNode defaultNode)
    Since:
      3.1

  - ### getMaxIdQualifierSize

    public int getMaxIdQualifierSize()
    Returns a maximum number of object IDs to match in a single query for queries that select objects based on collection of ObjectIds. This affects queries generated by Cayenne when processing paginated queries and DISJOINT_BY_ID prefetches and is intended to address database limitations on the size of SQL statements as well as to cap memory use in Cayenne when generating such queries. The default is 10000. It can be changed either by calling `setMaxIdQualifierSize(int)` or changing the value for property `Constants.MAX_ID_QUALIFIER_SIZE_PROPERTY`.
    Since:
      3.1

  - ### setMaxIdQualifierSize

    public void setMaxIdQualifierSize(int maxIdQualifierSize)
    Since:
      3.1