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 and Description
    --- | ---
    `protected DataNode` | `defaultNode`
    `protected EntityResolver` | `entityResolver`
    `protected EntitySorter` | `entitySorter`
    `protected EventManager` | `eventManager`
    `protected List<DataChannelFilter>` | `filters`
    `protected JdbcEventLogger` | `jdbcEventLogger`
    `protected int` | `maxIdQualifierSize`
    `protected String` | `name`
    `protected Map<String,DataNode>` | `nodes`
    `protected Map<String,DataNode>` | `nodesByDataMapName`
    `protected Map<String,String>` | `properties`
    `protected QueryCache` | `queryCache`
    `static boolean` | `SHARED_CACHE_ENABLED_DEFAULT`
    `static String` | `SHARED_CACHE_ENABLED_PROPERTY`
    `protected boolean` | `sharedCacheEnabled`
    `protected DataRowStore` | `sharedSnapshotCache`
    `protected boolean` | `stopped`
    `protected TransactionDelegate` | `transactionDelegate`
    `static boolean` | `USING_EXTERNAL_TRANSACTIONS_DEFAULT`
    `static String` | `USING_EXTERNAL_TRANSACTIONS_PROPERTY`
    `protected boolean` | `usingExternalTransactions`
    `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 and Description
    `DataDomain(String name)` Creates a DataDomain and assigns it a name.
    `DataDomain(String name, Map properties)` Creates new DataDomain.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDataMap(DataMap dataMap)`
    `void` | `addFilter(DataChannelFilter filter)` Adds a new filter, calling its 'init' method.
    `void` | `addMap(DataMap map)` Deprecated. since 3.1 use a more consistently named `addDataMap(DataMap)`.
    `void` | `addNode(DataNode node)` Adds new DataNode.
    `protected void` | `checkStopped()` Checks that Domain is not stopped.
    `void` | `clearDataMaps()` Deprecated. since 3.1 unused and unneeded
    `DataContext` | `createDataContext()` Deprecated. since 3.1 as context creation is done via `ObjectContextFactory` and injection.
    `DataContext` | `createDataContext(boolean useSharedCache)` Deprecated. since 3.1 as context creation is done via `ObjectContextFactory` and injection.
    `Transaction` | `createTransaction()` Creates and returns a new inactive transaction.
    `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.
    `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()` Returns an unmodifiable list of filters registered with this DataDomain.
    `DataMap` | `getMap(String mapName)` Deprecated. since 3.1 use a more consistently named `getDataMap(String)`.
    `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.
    `DataNode` | `getNode(String nodeName)` Deprecated. since 3.1, use a more consistently named `getDataNode(String)`.
    `Map<String,String>` | `getProperties()`
    `BatchQueryBuilderFactory` | `getQueryBuilderFactory()` Deprecated. since 3.1 BatchQueryBuilderFactory is injected into JdbcAdapter.
    `QueryCache` | `getQueryCache()` Returns shared `QueryCache` used by this DataDomain.
    `DataRowStore` | `getSharedSnapshotCache()` Returns snapshots cache for this DataDomain, lazily initializing it on the first call if 'sharedCacheEnabled' flag is true.
    `TransactionDelegate` | `getTransactionDelegate()`
    `void` | `initWithProperties(Map<String,String> properties)` Reinitializes domain state with a new set of properties.
    `boolean` | `isSharedCacheEnabled()` Returns `true` if DataContexts produced by this DataDomain are using shared DataRowStore.
    `boolean` | `isUsingExternalTransactions()` Returns whether this DataDomain should internally commit all transactions, or let container do that.
    `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` | `reindexNodes()` Deprecated. since 3.1 - unneeded and unused.
    `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)` Removes a filter from the filter chain.
    `void` | `removeMap(String mapName)` Deprecated. since 3.1 use a more consistently named `removeDataMap(String)`.
    `void` | `reset()` Deprecated. since 3.1 unused and unneeded
    `protected void` | `resetProperties()`
    `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` | `setQueryBuilderFactory(BatchQueryBuilderFactory queryBuilderFactory)` Deprecated. since 3.1 BatchQueryBuilderFactory is injected into JdbcAdapter.
    `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` | `setTransactionDelegate(TransactionDelegate transactionDelegate)` Initializes TransactionDelegate used by all DataContexts associated with this DataDomain.
    `void` | `setUsingExternalTransactions(boolean flag)` Sets a property defining whether this DataDomain should internally commit all transactions, or let container do that.
    `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

    - #### USING_EXTERNAL_TRANSACTIONS_PROPERTY

          public static final String USING_EXTERNAL_TRANSACTIONS_PROPERTY

      See Also:
        Constant Field Values

    - #### USING_EXTERNAL_TRANSACTIONS_DEFAULT

          public static final boolean USING_EXTERNAL_TRANSACTIONS_DEFAULT

      See Also:
        Constant Field Values

    - #### jdbcEventLogger

          protected JdbcEventLogger jdbcEventLogger

      Since:
        3.1

    - #### maxIdQualifierSize

          protected int maxIdQualifierSize

      Since:
        3.1

    - #### filters

          protected List<DataChannelFilter> filters

      Since:
        3.1

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

    - #### transactionDelegate

          protected TransactionDelegate transactionDelegate

    - #### name

          protected String name

    - #### queryCache

          protected QueryCache queryCache

    - #### sharedCacheEnabled

          protected boolean sharedCacheEnabled

    - #### validatingObjectsOnCommit

          protected boolean validatingObjectsOnCommit

    - #### usingExternalTransactions

          protected boolean usingExternalTransactions

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

          public DataDomain(String name,
                    Map properties)

      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

          public void initWithProperties(Map<String,String> properties)

      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. See `createDataContext(boolean)`.

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

    - #### isUsingExternalTransactions

          public boolean isUsingExternalTransactions()

      Returns whether this DataDomain should internally commit all transactions, or let container do that.
      Since:
        1.1

    - #### setUsingExternalTransactions

          public void setUsingExternalTransactions(boolean flag)

      Sets a property defining whether this DataDomain should internally commit all transactions, or let container do that.
      Since:
        1.1

    - #### getProperties

          public Map<String,String> getProperties()

      Returns:
        a Map of properties for this DataDomain.
      Since:
        1.1

    - #### getTransactionDelegate

          public TransactionDelegate getTransactionDelegate()

      Returns:
        TransactionDelegate associated with this DataDomain, or null if no delegate exist.
      Since:
        1.1

    - #### setTransactionDelegate

          public void setTransactionDelegate(TransactionDelegate transactionDelegate)

      Initializes TransactionDelegate used by all DataContexts associated with 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.

    - #### addMap

          @Deprecated
          public void addMap(DataMap map)

      Deprecated. since 3.1 use a more consistently named `addDataMap(DataMap)`.
      Registers new DataMap with this domain.

    - #### addDataMap

          public void addDataMap(DataMap dataMap)

    - #### getMap

          public DataMap getMap(String mapName)

      Deprecated. since 3.1 use a more consistently named `getDataMap(String)`.
      Returns DataMap matching `name` parameter.

    - #### getDataMap

          public DataMap getDataMap(String mapName)

      Since:
        3.1

    - #### removeMap

          @Deprecated
          public void removeMap(String mapName)

      Deprecated. since 3.1 use a more consistently named `removeDataMap(String)`.
      Removes named DataMap from this DataDomain and any underlying DataNodes that include it.

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

    - #### reset

          @Deprecated
          public void reset()

      Deprecated. since 3.1 unused and unneeded
      Closes all data nodes, removes them from the list of available nodes.

    - #### clearDataMaps

          @Deprecated
          public void clearDataMaps()

      Deprecated. since 3.1 unused and unneeded
      Clears the list of internal DataMaps.

    - #### addNode

          public void addNode(DataNode node)

      Adds new DataNode.

    - #### createDataContext

          @Deprecated
          public DataContext createDataContext()

      Deprecated. since 3.1 as context creation is done via `ObjectContextFactory` and injection.
      Creates and returns a new DataContext. If this DataDomain is configured to use shared cache, returned DataContext will use shared cache as well. Otherwise a new instance of DataRowStore will be used as its local cache.

    - #### createDataContext

          @Deprecated
          public DataContext createDataContext(boolean useSharedCache)

      Deprecated. since 3.1 as context creation is done via `ObjectContextFactory` and injection.
      Creates a new DataContext.
      Parameters:
        `useSharedCache` - determines whether resulting DataContext should use shared vs. local cache. This setting overrides default behavior configured for this DataDomain via `SHARED_CACHE_ENABLED_PROPERTY`.
      Since:
        1.1

    - #### createTransaction

          public Transaction createTransaction()

      Creates and returns a new inactive transaction. Returned transaction is bound to the current execution thread.

      If there is a TransactionDelegate, adds the delegate to the newly created Transaction. Behavior of the returned Transaction depends on "usingInternalTransactions" property setting.

      Since:
        1.1

    - #### getNode

          @Deprecated
          public DataNode getNode(String nodeName)

      Deprecated. since 3.1, use a more consistently named `getDataNode(String)`.
      Returns registered DataNode whose name matches `name` parameter.

    - #### getDataNode

          public DataNode getDataNode(String nodeName)

      Returns registered DataNode whose name matches `name` parameter.
      Since:
        3.1

    - #### reindexNodes

          @Deprecated
          public void reindexNodes()

      Deprecated. since 3.1 - unneeded and unused.
      Updates internal index of DataNodes stored by the entity name.

    - #### 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 `QueryEngine`
      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)

    - #### setQueryBuilderFactory

          @Deprecated
          public void setQueryBuilderFactory(BatchQueryBuilderFactory queryBuilderFactory)

      Deprecated. since 3.1 BatchQueryBuilderFactory is injected into JdbcAdapter.
      Sets factory for creating QueryBuilders

    - #### getQueryBuilderFactory

          @Deprecated
          public BatchQueryBuilderFactory getQueryBuilderFactory()

      Deprecated. since 3.1 BatchQueryBuilderFactory is injected into JdbcAdapter.
      Returns:
        factory for creating QueryBuilders. Might be null

    - #### getFilters

          public List<DataChannelFilter> getFilters()

      Returns an unmodifiable list of 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:
        3.1

    - #### addFilter

          public void addFilter(DataChannelFilter filter)

      Adds a new filter, calling its 'init' method.
      Since:
        3.1

    - #### removeFilter

          public void removeFilter(DataChannelFilter filter)

      Removes a filter from the filter chain.
      Since:
        3.1

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

Copyright © 2001–2014 Apache Cayenne. All rights reserved.