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

# Class DataMap

java.lang.Object
org.apache.cayenne.map.DataMap

All Implemented Interfaces:
  `Serializable, Comparable<DataMap>, ConfigurationNode, MappingNamespace, XMLSerializable`

public class DataMap extends Object implements Serializable, ConfigurationNode, XMLSerializable, MappingNamespace, Comparable<DataMap>
Stores a collection of related mapping objects that describe database and object layers of an application. DataMap contains DbEntities mapping database tables, ObjEntities - mapping persistent Java classes, Procedures - mapping database stored procedures.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Resource`
  `configurationSource`
  `protected DataChannelDescriptor`
  `dataChannelDescriptor`
  `static final String`
  `DEFAULT_CATALOG_PROPERTY`
  Defines the name of the property for default DB catalog.
  `static final String`
  `DEFAULT_LOCK_TYPE_PROPERTY`
  Defines the name of the property for default DB schema.
  `static final String`
  `DEFAULT_PACKAGE_PROPERTY`
  Defines the name of the property for default Java class package.
  `static final String`
  `DEFAULT_QUOTE_SQL_IDENTIFIERS_PROPERTY`
  `static final String`
  `DEFAULT_SCHEMA_PROPERTY`
  Defines the name of the property for default DB schema.
  `static final String`
  `DEFAULT_SUPERCLASS_PROPERTY`
  Defines the name of the property for default Java superclass.
  `protected String`
  `defaultCatalog`
  `protected int`
  `defaultLockType`
  `protected String`
  `defaultPackage`
  `protected String`
  `defaultSchema`
  `protected String`
  `defaultSuperclass`
  `protected String`
  `location`
  `protected String`
  `name`
  `protected MappingNamespace`
  `namespace`
  `protected Boolean`
  `quotingSQLIdentifiers`
  `static final String`
  `SCHEMA_XSD`
  The namespace in which the data map XML file will be created.
  `static final String`
  `SCHEMA_XSD_LOCATION`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataMap()`
  Creates a new unnamed DataMap.
  `DataMap(String mapName)`
  Creates a new named DataMap.
  `DataMap(String mapName, Map<String,Object> properties)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T> T`
  `acceptVisitor(ConfigurationNodeVisitor<T> visitor)`
  `void`
  `addDbEntity(DbEntity entity)`
  Adds a new DbEntity to this DataMap.
  `void`
  `addEmbeddable(Embeddable embeddable)`
  Adds an embeddable object to the DataMap.
  `void`
  `addObjEntity(ObjEntity entity)`
  Adds a new ObjEntity to this DataMap.
  `void`
  `addProcedure(Procedure procedure)`
  Adds stored procedure to the list of procedures.
  `void`
  `addQueryDescriptor(QueryDescriptor queryDescriptor)`
  Stores a query descriptor under its name.
  `void`
  `addResult(SQLResult result)`
  Adds a named SQLResultSet to the DataMap.
  `void`
  `clear()`
  `void`
  `clearDbEntities()`
  `void`
  `clearEmbeddables()`
  Removes all stored embeddable objects from the map.
  `void`
  `clearObjEntities()`
  `void`
  `clearProcedures()`
  `void`
  `clearQueries()`
  `void`
  `clearResultSets()`
  `int`
  `compareTo(DataMap o)`
  `void`
  `encodeAsXML(XMLEncoder encoder, ConfigurationNodeVisitor delegate)`
  Prints itself as XML to the provided PrintWriter.
  `Resource`
  `getConfigurationSource()`
  `DataChannelDescriptor`
  `getDataChannelDescriptor()`
  `Collection<DbEntity>`
  `getDbEntities()`
  Returns all DbEntities in this DataMap.
  `DbEntity`
  `getDbEntity(String dbEntityName)`
  Returns DbEntity matching the `name` parameter.
  `Map<String,DbEntity>`
  `getDbEntityMap()`
  Returns a unmodifiable map of DbEntities contained in this DataMap, keyed by DbEntity name.
  `String`
  `getDefaultCatalog()`
  `int`
  `getDefaultLockType()`
  `String`
  `getDefaultPackage()`
  `String`
  `getDefaultSchema()`
  `String`
  `getDefaultSuperclass()`
  `Embeddable`
  `getEmbeddable(String className)`
  Returns an `Embeddable` matching class name or null if such Embeddable is not mapped.
  `Map<String, Embeddable>`
  `getEmbeddableMap()`
  `Collection<Embeddable>`
  `getEmbeddables()`
  Returns a collection of `Embeddable` mappings stored in the DataMap.
  `EntityInheritanceTree`
  `getInheritanceTree(String entityName)`
  `String`
  `getLocation()`
  Returns "location" property value.
  `Collection<ObjEntity>`
  `getMappedEntities(DbEntity dbEntity)`
  Returns all ObjEntities mapped to the given DbEntity.
  `String`
  `getName()`
  Returns the name of this DataMap.
  `MappingNamespace`
  `getNamespace()`
  Returns a parent namespace where this DataMap resides.
  `String`
  `getNameWithDefaultPackage(String name)`
  `static String`
  `getNameWithPackage(String pack, String name)`
  `Collection<ObjEntity>`
  `getObjEntities()`
  Returns an unmodifiable collection of ObjEntities stored in this DataMap.
  `ObjEntity`
  `getObjEntity(Class<?> entityClass)`
  `ObjEntity`
  `getObjEntity(String objEntityName)`
  Returns an ObjEntity for a given name.
  `ObjEntity`
  `getObjEntity(Persistent object)`
  `ObjEntity`
  `getObjEntityForJavaClass(String javaClassName)`
  Returns an ObjEntity for a Persistent class name.
  `Map<String, ObjEntity>`
  `getObjEntityMap()`
  Returns a unmodifiable map of ObjEntities contained in this DataMap, keyed by ObjEntity name.
  `Procedure`
  `getProcedure(String procedureName)`
  Returns a Procedure for a given name or null if no such procedure exists.
  `Map<String, Procedure>`
  `getProcedureMap()`
  Returns a sorted unmodifiable map of Procedures in this DataMap keyed by name.
  `Collection<Procedure>`
  `getProcedures()`
  Returns stored procedures associated with this DataMap.
  `QueryDescriptor`
  `getQueryDescriptor(String queryName)`
  Returns a named query associated with this DataMap.
  `Map<String, QueryDescriptor>`
  `getQueryDescriptorMap()`
  `Collection<QueryDescriptor>`
  `getQueryDescriptors()`
  Returns an unmodifiable collection of mapped queries.
  `SQLResult`
  `getResult(String name)`
  Returns a named result set mapping.
  `Collection<SQLResult>`
  `getResults()`
  `Map<String, SQLResult>`
  `getResultsMap()`
  `Map<String, ObjEntity>`
  `getSubclassesForObjEntity(ObjEntity superEntity)`
  `void`
  `initWithProperties(Map<String,Object> properties)`
  Performs DataMap initialization from a set of properties, using defaults for the missing properties.
  `boolean`
  `isQuotingSQLIdentifiers()`
  `void`
  `mergeWithDataMap(DataMap map)`
  Adds all Object and DB entities and Queries from another map to this map.
  `void`
  `removeDbEntity(String dbEntityName)`
  "Dirty" remove of the DbEntity from the data map.
  `void`
  `removeDbEntity(String dbEntityName, boolean clearDependencies)`
  Removes DbEntity from the DataMap.
  `void`
  `removeEmbeddable(String className)`
  Removes an `Embeddable` descriptor with matching class name.
  `void`
  `removeObjEntity(String objEntityName)`
  "Dirty" remove of the ObjEntity from the data map.
  `void`
  `removeObjEntity(String objEntityName, boolean clearDependencies)`
  Removes ObjEntity from the DataMap.
  `void`
  `removeProcedure(String name)`
  `void`
  `removeQueryDescriptor(String queryName)`
  Removes a named query from the DataMap.
  `void`
  `removeResult(String name)`
  `void`
  `renameDbEntity(DbEntity entity, String newName)`
  Renames a `DbEntity` that belongs to this DataMap, re-keying the entity map and fixing up dependent references (incoming DbRelationship targets, ObjEntity dbEntityNames) and refreshing the parent namespace cache.
  `void`
  `renameObjEntity(ObjEntity entity, String newName)`
  Renames an `ObjEntity` that belongs to this DataMap, re-keying the entity map and fixing up dependent references (reverse ObjRelationship targets) and refreshing the parent namespace cache.
  `void`
  `setConfigurationSource(Resource configurationSource)`
  `void`
  `setDataChannelDescriptor(DataChannelDescriptor dataChannelDescriptor)`
  `void`
  `setDefaultCatalog(String defaultCatalog)`
  `void`
  `setDefaultLockType(int defaultLockType)`
  `void`
  `setDefaultPackage(String defaultPackage)`
  `void`
  `setDefaultSchema(String defaultSchema)`
  `void`
  `setDefaultSuperclass(String defaultSuperclass)`
  `void`
  `setLocation(String location)`
  Sets "location" property.
  `void`
  `setName(String name)`
  Set the name of this DataMap.
  `void`
  `setNamespace(MappingNamespace namespace)`
  Sets a parent namespace where this DataMap resides.
  `void`
  `setQuotingSQLIdentifiers(boolean quotingSqlIdentifiers)`
  `String`
  `toString()`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### DEFAULT_CATALOG_PROPERTY

    public static final String DEFAULT_CATALOG_PROPERTY
    Defines the name of the property for default DB catalog.
    Since:
      4.0
    See Also:
      - Constant Field Values

  - ### DEFAULT_SCHEMA_PROPERTY

    public static final String DEFAULT_SCHEMA_PROPERTY
    Defines the name of the property for default DB schema.
    Since:
      1.1
    See Also:
      - Constant Field Values

  - ### DEFAULT_PACKAGE_PROPERTY

    public static final String DEFAULT_PACKAGE_PROPERTY
    Defines the name of the property for default Java class package.
    Since:
      1.1
    See Also:
      - Constant Field Values

  - ### DEFAULT_SUPERCLASS_PROPERTY

    public static final String DEFAULT_SUPERCLASS_PROPERTY
    Defines the name of the property for default Java superclass.
    Since:
      1.1
    See Also:
      - Constant Field Values

  - ### DEFAULT_LOCK_TYPE_PROPERTY

    public static final String DEFAULT_LOCK_TYPE_PROPERTY
    Defines the name of the property for default DB schema.
    Since:
      1.1
    See Also:
      - Constant Field Values

  - ### DEFAULT_QUOTE_SQL_IDENTIFIERS_PROPERTY

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

  - ### SCHEMA_XSD

    public static final String SCHEMA_XSD
    The namespace in which the data map XML file will be created. This is also the URI to locate a copy of the schema document.
    See Also:
      - Constant Field Values

  - ### SCHEMA_XSD_LOCATION

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

  - ### name

    protected String name

  - ### location

    protected String location

  - ### namespace

    protected MappingNamespace namespace

  - ### quotingSQLIdentifiers

    protected Boolean quotingSQLIdentifiers

  - ### defaultCatalog

    protected String defaultCatalog

  - ### defaultSchema

    protected String defaultSchema

  - ### defaultPackage

    protected String defaultPackage

  - ### defaultSuperclass

    protected String defaultSuperclass

  - ### defaultLockType

    protected int defaultLockType

  - ### configurationSource

    protected transient Resource configurationSource
    Since:
      3.1

  - ### dataChannelDescriptor

    protected DataChannelDescriptor dataChannelDescriptor
    Since:
      3.1

- ## Constructor Details

  - ### DataMap

    public DataMap()
    Creates a new unnamed DataMap.

  - ### DataMap

    public DataMap(String mapName)
    Creates a new named DataMap.

  - ### DataMap

    public DataMap(String mapName, Map<String,Object> properties)

- ## Method Details

  - ### getDataChannelDescriptor

    public DataChannelDescriptor getDataChannelDescriptor()
    Since:
      3.1

  - ### setDataChannelDescriptor

    public void setDataChannelDescriptor(DataChannelDescriptor dataChannelDescriptor)
    Since:
      3.1

  - ### acceptVisitor

    public <T> T acceptVisitor(ConfigurationNodeVisitor<T> visitor)
    Specified by:
      `acceptVisitor` in interface `ConfigurationNode`
    Since:
      3.1

  - ### compareTo

    public int compareTo(DataMap o)
    Specified by:
      `compareTo` in interface `Comparable<DataMap>`
    Since:
      3.1

  - ### isQuotingSQLIdentifiers

    public boolean isQuotingSQLIdentifiers()
    Since:
      3.0

  - ### setQuotingSQLIdentifiers

    public void setQuotingSQLIdentifiers(boolean quotingSqlIdentifiers)
    Since:
      3.0

  - ### initWithProperties

    public void initWithProperties(Map<String,Object> properties)
    Performs DataMap initialization from a set of properties, using defaults for the missing properties.
    Since:
      1.1

  - ### encodeAsXML

    public void encodeAsXML(XMLEncoder encoder, ConfigurationNodeVisitor delegate)
    Prints itself as XML to the provided PrintWriter.
    Specified by:
      `encodeAsXML` in interface `XMLSerializable`
    Since:
      1.1

  - ### toString

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

  - ### getName

    public String getName()
    Returns the name of this DataMap.

  - ### setName

    public void setName(String name)
    Set the name of this DataMap.

  - ### mergeWithDataMap

    public void mergeWithDataMap(DataMap map)
    Adds all Object and DB entities and Queries from another map to this map. Overwrites all existing entities and queries with the new ones.

    TODO: will need to implement advanced merge that allows different policies for overwriting entities / queries.

  - ### getLocation

    public String getLocation()
    Returns "location" property value. Location is abstract and can depend on how the DataMap was loaded. E.g. location can be a File on the filesystem or a location within a JAR.

  - ### setLocation

    public void setLocation(String location)
    Sets "location" property.

  - ### getObjEntityMap

    public Map<String, ObjEntity> getObjEntityMap()
    Returns a unmodifiable map of ObjEntities contained in this DataMap, keyed by ObjEntity name.

  - ### getDbEntityMap

    public Map<String,DbEntity> getDbEntityMap()
    Returns a unmodifiable map of DbEntities contained in this DataMap, keyed by DbEntity name.

  - ### getQueryDescriptor

    public QueryDescriptor getQueryDescriptor(String queryName)
    Returns a named query associated with this DataMap.
    Specified by:
      `getQueryDescriptor` in interface `MappingNamespace`
    Since:
      4.0

  - ### addQueryDescriptor

    public void addQueryDescriptor(QueryDescriptor queryDescriptor)
    Stores a query descriptor under its name.
    Since:
      1.1

  - ### removeQueryDescriptor

    public void removeQueryDescriptor(String queryName)
    Removes a named query from the DataMap.
    Since:
      4.0

  - ### clearEmbeddables

    public void clearEmbeddables()
    Removes all stored embeddable objects from the map.
    Since:
      3.0

  - ### clearResultSets

    public void clearResultSets()
    Since:
      3.0

  - ### clearQueries

    public void clearQueries()
    Since:
      1.1

  - ### clearObjEntities

    public void clearObjEntities()
    Since:
      1.2

  - ### clearDbEntities

    public void clearDbEntities()
    Since:
      1.2

  - ### clearProcedures

    public void clearProcedures()
    Since:
      1.2

  - ### getQueryDescriptorMap

    public Map<String, QueryDescriptor> getQueryDescriptorMap()
    Since:
      4.0

  - ### getQueryDescriptors

    public Collection<QueryDescriptor> getQueryDescriptors()
    Returns an unmodifiable collection of mapped queries.
    Specified by:
      `getQueryDescriptors` in interface `MappingNamespace`
    Since:
      4.0

  - ### addEmbeddable

    public void addEmbeddable(Embeddable embeddable)
    Adds an embeddable object to the DataMap.
    Since:
      3.0

  - ### addResult

    public void addResult(SQLResult result)
    Adds a named SQLResultSet to the DataMap.
    Since:
      3.0

  - ### addObjEntity

    public void addObjEntity(ObjEntity entity)
    Adds a new ObjEntity to this DataMap.

  - ### addDbEntity

    public void addDbEntity(DbEntity entity)
    Adds a new DbEntity to this DataMap.

  - ### renameDbEntity

    public void renameDbEntity(DbEntity entity, String newName)
    Renames a `DbEntity` that belongs to this DataMap, re-keying the entity map and fixing up dependent references (incoming DbRelationship targets, ObjEntity dbEntityNames) and refreshing the parent namespace cache.
    Since:
      5.0

  - ### renameObjEntity

    public void renameObjEntity(ObjEntity entity, String newName)
    Renames an `ObjEntity` that belongs to this DataMap, re-keying the entity map and fixing up dependent references (reverse ObjRelationship targets) and refreshing the parent namespace cache.
    Since:
      5.0

  - ### getObjEntities

    public Collection<ObjEntity> getObjEntities()
    Returns an unmodifiable collection of ObjEntities stored in this DataMap.
    Specified by:
      `getObjEntities` in interface `MappingNamespace`

  - ### getEmbeddableMap

    public Map<String, Embeddable> getEmbeddableMap()
    Since:
      3.0

  - ### getEmbeddables

    public Collection<Embeddable> getEmbeddables()
    Returns a collection of `Embeddable` mappings stored in the DataMap.
    Specified by:
      `getEmbeddables` in interface `MappingNamespace`
    Since:
      3.0

  - ### getResultsMap

    public Map<String, SQLResult> getResultsMap()
    Since:
      3.0

  - ### getResults

    public Collection<SQLResult> getResults()
    Specified by:
      `getResults` in interface `MappingNamespace`
    Since:
      3.0

  - ### getEmbeddable

    public Embeddable getEmbeddable(String className)
    Description copied from interface: `MappingNamespace`
    Returns an `Embeddable` matching class name or null if such Embeddable is not mapped.
    Specified by:
      `getEmbeddable` in interface `MappingNamespace`
    Since:
      3.0

  - ### getResult

    public SQLResult getResult(String name)
    Description copied from interface: `MappingNamespace`
    Returns a named result set mapping.
    Specified by:
      `getResult` in interface `MappingNamespace`
    Since:
      3.0

  - ### getDbEntities

    public Collection<DbEntity> getDbEntities()
    Returns all DbEntities in this DataMap.
    Specified by:
      `getDbEntities` in interface `MappingNamespace`

  - ### getDbEntity

    public DbEntity getDbEntity(String dbEntityName)
    Returns DbEntity matching the `name` parameter. No dependencies will be searched.
    Specified by:
      `getDbEntity` in interface `MappingNamespace`

  - ### getObjEntityForJavaClass

    public ObjEntity getObjEntityForJavaClass(String javaClassName)
    Returns an ObjEntity for a Persistent class name.
    Since:
      1.1

  - ### getObjEntity

    public ObjEntity getObjEntity(String objEntityName)
    Returns an ObjEntity for a given name. If it is not found in this DataMap, it will search a parent EntityNamespace.
    Specified by:
      `getObjEntity` in interface `MappingNamespace`

  - ### getMappedEntities

    public Collection<ObjEntity> getMappedEntities(DbEntity dbEntity)
    Returns all ObjEntities mapped to the given DbEntity.

  - ### removeEmbeddable

    public void removeEmbeddable(String className)
    Removes an `Embeddable` descriptor with matching class name.
    Since:
      3.0

  - ### removeResult

    public void removeResult(String name)
    Since:
      3.0

  - ### removeDbEntity

    public void removeDbEntity(String dbEntityName)
    "Dirty" remove of the DbEntity from the data map.

  - ### removeDbEntity

    public void removeDbEntity(String dbEntityName, boolean clearDependencies)
    Removes DbEntity from the DataMap. If `clearDependencies` is true, all DbRelationships that reference this entity are also removed. ObjEntities that rely on this entity are cleaned up.
    Since:
      1.1

  - ### removeObjEntity

    public void removeObjEntity(String objEntityName)
    "Dirty" remove of the ObjEntity from the data map.

  - ### removeObjEntity

    public void removeObjEntity(String objEntityName, boolean clearDependencies)
    Removes ObjEntity from the DataMap. If `clearDependencies` is true, all ObjRelationships that reference this entity are also removed.
    Since:
      1.1

  - ### getProcedures

    public Collection<Procedure> getProcedures()
    Returns stored procedures associated with this DataMap.
    Specified by:
      `getProcedures` in interface `MappingNamespace`

  - ### getProcedure

    public Procedure getProcedure(String procedureName)
    Returns a Procedure for a given name or null if no such procedure exists. If Procedure is not found in this DataMap, a parent EntityNamcespace is searched.
    Specified by:
      `getProcedure` in interface `MappingNamespace`

  - ### addProcedure

    public void addProcedure(Procedure procedure)
    Adds stored procedure to the list of procedures. If there is another procedure registered under the same name, throws an IllegalArgumentException.

  - ### removeProcedure

    public void removeProcedure(String name)

  - ### getProcedureMap

    public Map<String, Procedure> getProcedureMap()
    Returns a sorted unmodifiable map of Procedures in this DataMap keyed by name.

  - ### getNamespace

    public MappingNamespace getNamespace()
    Returns a parent namespace where this DataMap resides. Parent EntityNamespace is used to establish relationships with entities in other DataMaps.
    Since:
      1.1

  - ### setNamespace

    public void setNamespace(MappingNamespace namespace)
    Sets a parent namespace where this DataMap resides. Parent EntityNamespace is used to establish relationships with entities in other DataMaps.
    Since:
      1.1

  - ### getDefaultLockType

    public int getDefaultLockType()
    Since:
      1.1

  - ### setDefaultLockType

    public void setDefaultLockType(int defaultLockType)
    Since:
      1.1

  - ### getDefaultPackage

    public String getDefaultPackage()
    Since:
      1.1

  - ### setDefaultPackage

    public void setDefaultPackage(String defaultPackage)
    Since:
      1.1

  - ### getDefaultSchema

    public String getDefaultSchema()
    Since:
      1.1

  - ### setDefaultSchema

    public void setDefaultSchema(String defaultSchema)
    Since:
      1.1

  - ### getDefaultSuperclass

    public String getDefaultSuperclass()
    Since:
      1.1

  - ### setDefaultSuperclass

    public void setDefaultSuperclass(String defaultSuperclass)
    Since:
      1.1

  - ### getConfigurationSource

    public Resource getConfigurationSource()
    Since:
      3.1

  - ### setConfigurationSource

    public void setConfigurationSource(Resource configurationSource)
    Since:
      3.1

  - ### getDefaultCatalog

    public String getDefaultCatalog()
    Since:
      4.0

  - ### setDefaultCatalog

    public void setDefaultCatalog(String defaultCatalog)
    Since:
      4.0

  - ### getInheritanceTree

    public EntityInheritanceTree getInheritanceTree(String entityName)
    Specified by:
      `getInheritanceTree` in interface `MappingNamespace`
    Since:
      4.0

  - ### getObjEntity

    public ObjEntity getObjEntity(Class<?> entityClass)
    Specified by:
      `getObjEntity` in interface `MappingNamespace`
    Since:
      4.0

  - ### getObjEntity

    public ObjEntity getObjEntity(Persistent object)
    Specified by:
      `getObjEntity` in interface `MappingNamespace`

  - ### clear

    public void clear()

  - ### getNameWithDefaultPackage

    public String getNameWithDefaultPackage(String name)
    Returns:
      package + "." + name when it is possible otherwise just name
    Since:
      4.0

  - ### getNameWithPackage

    public static String getNameWithPackage(String pack, String name)
    Returns:
      package + "." + name when it is possible otherwise just name
    Since:
      4.0

  - ### getSubclassesForObjEntity

    public Map<String, ObjEntity> getSubclassesForObjEntity(ObjEntity superEntity)