Package org.apache.cayenne.access

## Class DataDomain

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

- All Implemented Interfaces:
    `QueryEngine`, `DataChannel`

      public class DataDomain
      extends Object
      implements QueryEngine, 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 List<DataChannelFilter>` | `filters` | Deprecated. since 4.1 this field is unused
    `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 boolean` | `SHARED_CACHE_ENABLED_DEFAULT` |
    `static String` | `SHARED_CACHE_ENABLED_PROPERTY` |
    `protected boolean` | `sharedCacheEnabled` |
    `protected DataRowStore` | `sharedSnapshotCache` |
    `protected boolean` | `stopped` |
    `protected List<DataChannelSyncFilter>` | `syncFilters` |
    `protected TransactionManager` | `transactionManager` |
    `static boolean` | `VALIDATING_OBJECTS_ON_COMMIT_DEFAULT` |
    `static String` | `VALIDATING_OBJECTS_ON_COMMIT_PROPERTY` |
    `protected boolean` | `validatingObjectsOnCommit` |

    - ### Fields inherited from interface org.apache.cayenne.DataChannel

      `FLUSH_CASCADE_SYNC, FLUSH_NOCASCADE_SYNC, GRAPH_CHANGED_SUBJECT, GRAPH_FLUSHED_SUBJECT, GRAPH_ROLLEDBACK_SUBJECT, ROLLBACK_CASCADE_SYNC`

  - ### 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

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addDataMap​(DataMap dataMap)` |
    `void` | `addFilter​(DataChannelFilter filter)` | Deprecated. since 4.1 use `addQueryFilter(DataChannelQueryFilter)` and `addSyncFilter(DataChannelSyncFilter)` instead
    `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.
    `List<DataChannelFilter>` | `getFilters()` | Deprecated. since 4.1 use `getQueryFilters()` and `getSyncFilters()`
    `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)` | Routes queries to appropriate DataNodes for execution.
    `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` | `removeFilter​(DataChannelFilter filter)` | Deprecated. since 4.1 use `removeQueryFilter(DataChannelQueryFilter)` and `removeSyncFilter(DataChannelSyncFilter)` instead
    `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 java.lang.Object

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

- - ### Field Detail

    - #### 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

    - #### filters

          @Deprecated
          protected List<DataChannelFilter> filters

      Deprecated.
      since 4.1 this field is unused
      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 Detail

    - #### 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 Detail

    - #### 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

          public void performQueries​(Collection<? extends Query> queries,
                                     OperationObserver callback)

      Routes queries to appropriate DataNodes for execution.
      Specified by:
        `performQueries` in interface `QueryEngine`

    - #### 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`
      Specified by:
        `getEntityResolver` in interface `QueryEngine`

    - #### 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

    - #### getFilters

          @Deprecated
          public List<DataChannelFilter> getFilters()

      Deprecated.
      since 4.1 use `getQueryFilters()` and `getSyncFilters()`
      Since 4.1 returns empty list.
      Since:
        3.1

    - #### 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

    - #### addFilter

          @Deprecated
          public void addFilter​(DataChannelFilter filter)

      Deprecated.
      since 4.1 use `addQueryFilter(DataChannelQueryFilter)` and `addSyncFilter(DataChannelSyncFilter)` instead
      Adds a new filter, immediately calling its 'init' method. Since 4.0 this method also registers passed filter as an event listener, if any of its methods have event annotations.
      Since:
        3.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

    - #### removeFilter

          @Deprecated
          public void removeFilter​(DataChannelFilter filter)

      Deprecated.
      since 4.1 use `removeQueryFilter(DataChannelQueryFilter)` and `removeSyncFilter(DataChannelSyncFilter)` instead
      Removes a filter from the filter chain.
      Since:
        3.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.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY`.
      Since:
        3.1

    - #### setMaxIdQualifierSize

          public void setMaxIdQualifierSize​(int maxIdQualifierSize)

      Since:
        3.1