* Copyright (c) 1998, 2013 Oracle and/or its affiliates. All rights reserved.

* This program and the accompanying materials are made available under the

* terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0

* which accompanies this distribution.

* The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html

* and the Eclipse Distribution License is available at

* http://www.eclipse.org/org/documents/edl-v10.php.

*

* Contributors:

*     05/16/2008-1.0M8 Guy Pelletier

*       - 218084: Implement metadata merging functionality between mapping files

*     06/20/2008-1.0 Guy Pelletier

*       - 232975: Failure when attribute type is generic

*     08/27/2008-1.1 Guy Pelletier

*       - 211329: Add sequencing on non-id attribute(s) support to the EclipseLink-ORM.XML Schema

*     09/23/2008-1.1 Guy Pelletier

*       - 241651: JPA 2.0 Access Type support

*     01/28/2009-2.0 Guy Pelletier

*       - 248293: JPA 2.0 Element Collections (part 1)

*     02/06/2009-2.0 Guy Pelletier

*       - 248293: JPA 2.0 Element Collections (part 2)

*     02/25/2009-2.0 Guy Pelletier

*       - 265359: JPA 2.0 Element Collections - Metadata processing portions

*     03/27/2009-2.0 Guy Pelletier

*       - 241413: JPA 2.0 Add EclipseLink support for Map type attributes

*     04/03/2009-2.0 Guy Pelletier

*       - 241413: JPA 2.0 Add EclipseLink support for Map type attributes

*     04/24/2009-2.0 Guy Pelletier

*       - 270011: JPA 2.0 MappedById support

*     06/02/2009-2.0 Guy Pelletier

*       - 278768: JPA 2.0 Association Override Join Table

*     06/25/2009-2.0 Michael O'Brien

*       - 266912: change MappedSuperclass handling in stage2 to pre process accessors

*          in support of the custom descriptors holding mappings required by the Metamodel.

*          We handle undefined parameterized generic types for a MappedSuperclass defined

*          Map field by returning Void in this case.

*     09/29/2009-2.0 Guy Pelletier

*       - 282553: JPA 2.0 JoinTable support for OneToOne and ManyToOne

*     10/21/2009-2.0 Guy Pelletier

*       - 290567: mappedbyid support incomplete

*     11/06/2009-2.0 Guy Pelletier

*       - 286317: UniqueConstraint xml element is changing (plus couple other fixes, see bug)

*     01/22/2010-2.0.1 Guy Pelletier

*       - 294361: incorrect generated table for element collection attribute overrides

*     01/26/2010-2.0.1 Guy Pelletier

*       - 299893: @MapKeyClass does not work with ElementCollection

*     03/08/2010-2.1 Guy Pelletier

*       - 303632: Add attribute-type for mapping attributes to EclipseLink-ORM

*     03/29/2010-2.1 Guy Pelletier

*       - 267217: Add Named Access Type to EclipseLink-ORM

*     04/09/2010-2.1 Guy Pelletier

*       - 307050: Add defaults for access methods of a VIRTUAL access type

*     04/27/2010-2.1 Guy Pelletier

*       - 309856: MappedSuperclasses from XML are not being initialized properly

*     05/19/2010-2.1 Guy Pelletier

*       - 313574: Lower case primary key column association does not work when upper casing flag is set to true

*     06/14/2010-2.2 Guy Pelletier

*       - 264417: Table generation is incorrect for JoinTables in AssociationOverrides

*     07/05/2010-2.1.1 Guy Pelletier

*       - 317708: Exception thrown when using LAZY fetch on VIRTUAL mapping

*     08/20/2010-2.2 Guy Pelletier

*       - 323252: Canonical model generator throws NPE on virtual 1-1 or M-1 mapping

*     09/03/2010-2.2 Guy Pelletier

*       - 317286: DB column lenght not in sync between @Column and @JoinColumn

*     10/27/2010-2.2 Guy Pelletier

*       - 328114: @AttributeOverride does not work with nested embeddables having attributes of the same name

*     12/01/2010-2.2 Guy Pelletier

*       - 331234: xml-mapping-metadata-complete overriden by metadata-complete specification

*     03/24/2011-2.3 Guy Pelletier

*       - 337323: Multi-tenant with shared schema support (part 1)

*     11/10/2011-2.4 Guy Pelletier

*       - 357474: Address primaryKey option from tenant discriminator column

*     25/05/2012-2.4 Guy Pelletier 

*       - 354678: Temp classloader is still being used during metadata processing

******************************************************************************/

* INTERNAL:

* An abstract mapping accessor. Holds common metadata for all mappings.

*

* Key notes:

* - any metadata mapped from XML to this class must be compared in the

*   equals method.

* - any metadata mapped from XML to this class must be handled in the merge

*   method. (merging is done at the accessor/mapping level)

* - any metadata mapped from XML to this class must be initialized in the

*   initXMLObject  method.

* - methods should be preserved in alphabetical order.

*

* @author Guy Pelletier

* @since EclipseLink 1.0

*/

    // Reserved converter names

    private static final String CONVERT_NONE = "none";

    private static final String CONVERT_SERIALIZED = "serialized";

    private static final String CONVERT_CLASS_INSTANCE = "class-instance";

    // Used for looking up attribute overrides for a map accessor.

    protected static final String KEY_DOT_NOTATION = "key.";

    protected static final String VALUE_DOT_NOTATION = "value.";

    private final static String DEFAULT_MAP_KEY_COLUMN_SUFFIX = "_KEY";

    private ClassAccessor m_classAccessor;

    private DatabaseMapping m_mapping;

    private DatabaseMapping m_overrideMapping;

    private Map<String, PropertyMetadata> m_properties = new HashMap<String, PropertyMetadata>();

    private String m_attributeType;

    protected ColumnMetadata m_field;

   

    /**

     * INTERNAL:

     */

    protected MappingAccessor(MetadataAnnotation annotation, MetadataAccessibleObject accessibleObject, ClassAccessor classAccessor) {

        super(annotation, accessibleObject, classAccessor.getDescriptor(), classAccessor.getProject());

       

        // We must keep a reference to the class accessors where this

        // mapping accessor is defined. We need it to determine access types.

        m_classAccessor = classAccessor;

       

        // Once the class accessor is initialized, we can look for an explicit

        // access type specification.

        initAccess();

        // Any mapping type may have a field for EIS/NoSQL data.

        MetadataAnnotation field = getAnnotation("org.eclipse.persistence.nosql.annotations.Field");

        if (field != null) {

            m_field = new ColumnMetadata(field, this);

        }

    }

   

    /**

     * INTERNAL:

     */

    protected MappingAccessor(String xmlElement) {

        super(xmlElement);

    }

   

    /**

     * INTERNAL:

     * Return true is this accessor is a derived id accessor.

     * @see ObjectAccessor

     */

    public boolean derivesId() {

        return false;

    }

   

    /**

     * INTERNAL:

     * For merging and overriding to work properly, all ORMetadata must be able

     * to compare themselves for metadata equality.

     */

    @Override

    public boolean equals(Object objectToCompare) {

        if (super.equals(objectToCompare) && objectToCompare instanceof MappingAccessor) {

            MappingAccessor mappingAccessor = (MappingAccessor) objectToCompare;

           

            // For extra safety compare that the owning class accessors of these

            // mapping accessors are the same.

            if (! valuesMatch(getClassAccessor(), mappingAccessor.getClassAccessor())) {

                return false;

            }

            if (! valuesMatch(m_field, mappingAccessor.getField())) {

                return false;

            }

           

            return valuesMatch(getAttributeType(), mappingAccessor.getAttributeType());

        }

       

        return false;

    }

   

    /**

     * INTERNAL:

     * Process an attribute override for either an embedded object mapping, or

     * an element collection mapping containing embeddable objects.

     */

    protected void addFieldNameTranslation(EmbeddableMapping embeddableMapping, String overrideName, DatabaseField overrideField, MappingAccessor aggregatesAccessor) {

        DatabaseMapping aggregatesMapping = aggregatesAccessor.getMapping();

        DatabaseField aggregatesMappingField = aggregatesMapping.getField();

       

        // If we are specifying an attribute override to an id field that is

        // within the embeddable we must update the primary key field on the

        // owning descriptor.

        if (aggregatesAccessor.isId()) {

            updatePrimaryKeyField(aggregatesAccessor, overrideField);

        }

       

        if (overrideName.indexOf(".") > -1) {

            // Set the nested field name translation on the mapping. Nested

            // (dot notation) overrides are initialized slightly different then

            // core field name translations which are based on column names. In

            // JPA we need to rely and differentiate based on the override

            // (attribute) name.

            embeddableMapping.addNestedFieldTranslation(overrideName, overrideField, aggregatesMappingField.getName());

        } else {

            // Set the field name translation on the mapping.

            embeddableMapping.addFieldTranslation(overrideField, aggregatesMappingField.getName());

        }

    }

   

    /**

     * INTERNAL:

     * Return the annotation if it exists.

     */

    @Override

    protected MetadataAnnotation getAnnotation(String annotation) {

        return getAccessibleObject().getAnnotation(annotation, getClassAccessor());

    }

   

    /**

     * INTERNAL:

     * Process the list of association overrides into a map, merging and

     * overriding any association overrides where necessary with descriptor

     * level association overrides.

     */

    protected Map<String, AssociationOverrideMetadata> getAssociationOverrides(List<AssociationOverrideMetadata> associationOverrides) {

        // TODO: Be nice to look for duplicates within the same list.

        Map<String, AssociationOverrideMetadata> associationOverridesMap = new HashMap<String, AssociationOverrideMetadata>();

       

        for (AssociationOverrideMetadata associationOverride : associationOverrides) {

            String name = associationOverride.getName();

           

            // An association override from a sub-entity class will name its

            // association override slightly different in that it will have

            // one extra dot notation at the front. E.G. A mapped superclass

            // that defines an embedded attribute named 'record' can define

            // association overrides directly on the mapping, that is,

            // 'date'. Whereas from an entity class to override 'date' on

            // 'record', the attribute name will be 'record.date'

            String dotNotationName = getAttributeName() + "." + name;

            if (getClassAccessor().isMappedSuperclass() && getDescriptor().hasAssociationOverrideFor(dotNotationName)) {

                getLogger().logConfigMessage(getLogger().IGNORE_ASSOCIATION_OVERRIDE, name, getAttributeName(), getClassAccessor().getJavaClassName(), getJavaClassName());

                associationOverridesMap.put(name, getDescriptor().getAssociationOverrideFor(dotNotationName));

            } else {

                associationOverridesMap.put(name, associationOverride);

            }

        }

       

        // Now add every other descriptor association override that didn't

        // override a mapping level one (if we are processing a mapping from

        // a mapped superclass level). We'll check the attribute names match

        // and rip off the extra qualifying when adding it to the override map.

        if (getClassAccessor().isMappedSuperclass()) {

            for (AssociationOverrideMetadata associationOverride : getDescriptor().getAssociationOverrides()) {

                String name = associationOverride.getName();

                String attributeName = name;

                String overrideName = name;

                int indexOfFirstDot = name.indexOf(".");               

                if (indexOfFirstDot > -1) {

                    attributeName = name.substring(0, indexOfFirstDot);

                    overrideName = name.substring(indexOfFirstDot + 1);

                }

                

                if (attributeName.equals(getAttributeName()) && ! associationOverridesMap.containsKey(attributeName)) {

                    associationOverridesMap.put(overrideName, associationOverride);

                }

            }

        }

       

        return associationOverridesMap;

    }

   

    /**

     * INTERNAL:

     * Return the attribute name for this accessor. This is typically the

     * attribute name on the accessible object (i.e., field or property name),

     * however, if access-methods have been specified, use the name attribute

     * that was specified in XML. (e.g. basic name="sin") and not the property

     * name of the get method from the access-methods specification.

     */

    @Override

    public String getAttributeName() {

        if (hasAccessMethods()) {

            return getName();

        } else {

            return getAccessibleObject().getAttributeName();

        }

    }

   

    /**

     * INTERNAL:

     * Return the attribute override for this accessor.

     */

    protected AttributeOverrideMetadata getAttributeOverride(String loggingCtx) {

        if (loggingCtx.equals(MetadataLogger.MAP_KEY_COLUMN)) {

            return getDescriptor().getAttributeOverrideFor(KEY_DOT_NOTATION + getAttributeName());

        } else if (loggingCtx.equals(MetadataLogger.VALUE_COLUMN)) {

            if (getDescriptor().hasAttributeOverrideFor(VALUE_DOT_NOTATION + getAttributeName())) {

                return getDescriptor().getAttributeOverrideFor(VALUE_DOT_NOTATION + getAttributeName());

            }

        }

           

        return getDescriptor().getAttributeOverrideFor(getAttributeName());

    }

   

    /**

     * INTERNAL:

     * Process the list of attribute overrides into a map, merging and

     * overriding any attribute overrides where necessary with descriptor

     * level attribute overrides.

     */

    protected Map<String, AttributeOverrideMetadata> getAttributeOverrides(List<AttributeOverrideMetadata> attributeOverrides) {

        // TODO: Be nice to look for duplicates within the same list.

        HashMap<String, AttributeOverrideMetadata> attributeOverridesMap = new HashMap<String, AttributeOverrideMetadata>();

       

        for (AttributeOverrideMetadata attributeOverride : attributeOverrides) {

            String name = attributeOverride.getName();

           

            // An attribute override from a sub-entity class will name its

            // attribute override slightly different in that it will have one

            // extra dot notation at the front. E.G. A mapped superclass that

            // defines an embedded attribute named 'record' can define attribute

            // overrides directly on the mapping, that is, 'date'. Whereas

            // from an entity class to override 'date' on 'record', the

            // attribute name will be 'record.date'

            String dotNotationName = getAttributeName() + "." + name;

            if (getClassAccessor().isMappedSuperclass() && getDescriptor().hasAttributeOverrideFor(dotNotationName)) {

                getLogger().logConfigMessage(getLogger().IGNORE_ATTRIBUTE_OVERRIDE, name, getAttributeName(), getClassAccessor().getJavaClassName(), getJavaClassName());

                attributeOverridesMap.put(name, getDescriptor().getAttributeOverrideFor(dotNotationName));

            } else {

                attributeOverridesMap.put(name, attributeOverride);

            }

        }

       

        // Now add every other descriptor association override that didn't

        // override a mapping level one (if we are processing a mapping from

        // a mapped superclass level). We'll check the attribute names match

        // and rip off the extra qualifying when adding it to the override map.

        if (getClassAccessor().isMappedSuperclass()) {

            for (AttributeOverrideMetadata attributeOverride : getDescriptor().getAttributeOverrides()) {

                String name = attributeOverride.getName();

                String attributeName = name;

                String overrideName = name;

                int indexOfFirstDot = name.indexOf(".");               

                if (indexOfFirstDot > -1) {

                    attributeName = name.substring(0, indexOfFirstDot);

                    overrideName = name.substring(indexOfFirstDot + 1);

                }

                

                if (attributeName.equals(getAttributeName()) && ! attributeOverridesMap.containsKey(attributeName)) {

                    attributeOverridesMap.put(overrideName, attributeOverride);

                }

            }

        }

       

        return attributeOverridesMap;

    }

   

    /**

     * INTERNAL:

     * Used for OX mapping. Those accessors that do not require a separate

     * attribute-type specification for VIRTUAL accessors should override this

     * method. For example, one-to-one and many-to-one will its target-entity.

     * variable-one-to-one will use its target-interface.

     */

    public String getAttributeType() {

        return m_attributeType;

    }

   

    /**

     * INTERNAL:

     * Returns the class accessor on which this mapping was defined.

     */

    public ClassAccessor getClassAccessor(){

        return m_classAccessor;

    }

   

    /**

     * INTERNAL:

     * Subclasses should override this method to return the appropriate

     * column for their mapping.

     * @see BasicAccessor

     * @see BasicCollectionAccessor

     * @see BasicMapAccessor

     * @see ElementCollectionAccessor

     * @see CollectionAccessor

     */

    protected ColumnMetadata getColumn(String loggingCtx) {

        return m_field == null ? new ColumnMetadata(this) : m_field;

    }

   

    /**

     * INTERNAL:

     * Process column metadata details into a database field. This will set

     * correct metadata and log defaulting messages to the user. It also looks

     * for an attribute override.

     *

     * This method will call getColumn() which assumes the subclasses will

     * return the appropriate ColumnMetadata to process based on the context

     * provided.

     *

     * @See BasicCollectionAccessor and BasicMapAccessor.

     */

    protected DatabaseField getDatabaseField(DatabaseTable defaultTable, String loggingCtx) {

        // Check if we have an attribute override first, otherwise process for a column

        ColumnMetadata column  = hasAttributeOverride(loggingCtx) ? getAttributeOverride(loggingCtx).getColumn() : getColumn(loggingCtx);

       

        // Get the actual database field and apply any defaults.

        DatabaseField field = column.getDatabaseField();

          

        // Make sure there is a table name on the field.

        if (! field.hasTableName()) {

            field.setTable(defaultTable);

        }

       

        // We must check the flag before blindly setting it on the table since

        // global flag may be false where this fields table may explicitly use

        // delimiters.

        if (getProject().useDelimitedIdentifier()) {

            field.getTable().setUseDelimiters(true);

        }

       

        // Set the correct field name, defaulting and logging when necessary.

        String defaultName = getDefaultAttributeName();

          

        // If this is for a map key column, append a suffix.

        if (loggingCtx.equals(MetadataLogger.MAP_KEY_COLUMN)) {

            defaultName += DEFAULT_MAP_KEY_COLUMN_SUFFIX;

        }

       

        setFieldName(field, defaultName, loggingCtx);

        // Store all the fields for this descriptor. This will allow re-use

        // and easy lookup of referenced column names.

        getDescriptor().addField(field);

       

        return field;

    }

   

    /**

     * INTERNAL:

     */

    protected String getDefaultFetchType() {

        return JPA_FETCH_EAGER;

    }

   

    /**

     * INTERNAL:

     * Return the default table to hold the foreign key of a MapKey when

     * and Entity is used as the MapKey

     * @return

     */

    protected DatabaseTable getDefaultTableForEntityMapKey(){

        return getReferenceDescriptor().getPrimaryTable();

    }

   

    /**

     * INTERNAL:

     * Return the enumerated metadata for this accessor.

     * @see DirectAccessor

     * @see ElementCollectionAccessor

     * @see CollectionAccessor

     */

    public EnumeratedMetadata getEnumerated(boolean isForMapKey) {

        return null;

    }

   

    /**

     * INTERNAL:

     * Used for OX mapping.

     */

    public ColumnMetadata getField() {

        return m_field;

    }

   

    /**

     * INTERNAL:

     * Returns the get method name of a method accessor. Note, this method

     * should not be called when processing field access.

     */

    public String getGetMethodName() {

        return hasAccessMethods() ? getAccessMethods().getGetMethodName() : getAccessibleObjectName();

    }

   

    /**

     * INTERNAL:

     * Return the join columns to use with this mapping accessor. This method

     * will look for association overrides and use those instead if some are

     * available. This method will validate the join columns and default

     * any where necessary.

     */

    protected List<JoinColumnMetadata> getJoinColumns(List<JoinColumnMetadata> potentialJoinColumns, MetadataDescriptor descriptor) {

        if (getDescriptor().hasAssociationOverrideFor(getAttributeName())) {

            return getJoinColumnsAndValidate(getDescriptor().getAssociationOverrideFor(getAttributeName()).getJoinColumns(), descriptor);

        } else {

            return getJoinColumnsAndValidate(potentialJoinColumns, descriptor);

        }

    }

   

    /**

     * INTERNAL:

     * This method will validate the join columns and default any where

     * necessary.

     */   

    protected List<JoinColumnMetadata> getJoinColumnsAndValidate(List<JoinColumnMetadata> joinColumns, MetadataDescriptor referenceDescriptor) {

        if (joinColumns.isEmpty()) {

            if (referenceDescriptor.hasCompositePrimaryKey()) {

                // Add a default one for each part of the composite primary

                // key. Foreign and primary key to have the same name.

                for (DatabaseField primaryKeyField : referenceDescriptor.getPrimaryKeyFields()) {

                    // Multitenant primary key fields will be dealt with below so avoid adding here.

                    if (! primaryKeyField.isPrimaryKey()) {

                        JoinColumnMetadata joinColumn = new JoinColumnMetadata();

                        joinColumn.setReferencedColumnName(primaryKeyField.getName());

                        joinColumn.setName(primaryKeyField.getName());

                        joinColumn.setProject(referenceDescriptor.getProject());

                        joinColumns.add(joinColumn);

                    }

                }

            } else {

                // Add a default one for the single case, not setting any

                // foreign and primary key names. They will default based

                // on which accessor is using them.

                JoinColumnMetadata jcm = new JoinColumnMetadata();

                jcm.setProject(referenceDescriptor.getProject());

                joinColumns.add(jcm);

            }

        } else {

            // Need to update any join columns that use a foreign key name

            // for the primary key name. E.G. User specifies the renamed id

            // field name from a primary key join column as the primary key in

            // an inheritance subclass.

            for (JoinColumnMetadata joinColumn : joinColumns) {

                // Doing this could potentially change a value entered in XML.

                // However, in this case I think that is ok since in theory we

                // are writing out the correct value that EclipseLink needs to

                // form valid queries.

                String referencedColumnName = joinColumn.getReferencedColumnName();

                // The referenced column name in a variable one to one case is a

                // query key name and not a column name so bypass any of this

                // code.

                if (referencedColumnName != null && !isVariableOneToOne()) {

                    DatabaseField referencedField = new DatabaseField();

                    setFieldName(referencedField, referencedColumnName);

                    joinColumn.setReferencedColumnName(referenceDescriptor.getPrimaryKeyJoinColumnAssociation(referencedField).getName());

                }

            }

        }

       

        // Multitenant entities. Go through and add any multitenant primary key

        // fields that need to be added. The user may or may not specify them

        // in metadata.

        if (referenceDescriptor.hasSingleTableMultitenant() && joinColumns.size() != referenceDescriptor.getPrimaryKeyFields().size()) {

            Map<String, List<DatabaseField>> referenceTenantFields = referenceDescriptor.getSingleTableMultitenantFields();

               

            // If we are multitenant then we can sync up on relationship fields

            // using the context property.

            Map<String, List<DatabaseField>> tenantFields = getDescriptor().hasSingleTableMultitenant() ? getDescriptor().getSingleTableMultitenantFields() : null;

                   

            for (String contextProperty : referenceTenantFields.keySet()) {

                List<DatabaseField> referenceFields = referenceTenantFields.get(contextProperty);

                for (DatabaseField referenceField : referenceFields) {

                    // Only if it is a primary key field, otherwise we don't

                    // care about it.

                    if (referenceField.isPrimaryKey()) {

                        JoinColumnMetadata jcm = new JoinColumnMetadata();

                        // This join column must be read only.

                        jcm.setInsertable(false);

                        jcm.setUpdatable(false);

                       

                        // If we have a related context property, look up a

                        // field that matches from it.

                        if (tenantFields != null && tenantFields.containsKey(contextProperty)) {

                            // This is going to return a list just pick the first

                            // field (they populate the same value so doesn't really

                            // matter which one we pick.

                            jcm.setName(tenantFields.get(contextProperty).get(0).getName());

                        } else {

                            // We don't have a match, use the same name.

                            jcm.setName(referenceField.getName());

                        }

                           

                        jcm.setReferencedColumnName(referenceField.getName());

                        jcm.setProject(referenceDescriptor.getProject());

                        joinColumns.add(jcm);

                    }

                }

            }

        }

       

        // Now run some validation.

        if (referenceDescriptor.hasCompositePrimaryKey()) {

            // The number of join columns should equal the number of primary key fields.

            if (joinColumns.size() != referenceDescriptor.getPrimaryKeyFields().size()) {

                throw ValidationException.incompleteJoinColumnsSpecified(getAnnotatedElement(), getJavaClass());

            }

           

            // All the primary and foreign key field names should be specified.

            for (JoinColumnMetadata joinColumn : joinColumns) {

                if (joinColumn.isPrimaryKeyFieldNotSpecified() || joinColumn.isForeignKeyFieldNotSpecified()) {

                    throw ValidationException.incompleteJoinColumnsSpecified(getAnnotatedElement(), getJavaClass());

                }

            }

        }

       

        return joinColumns;

    }

   

    /**

     * INTERNAL:

     * Return the lob metadata for this accessor.

     * @see DirectAccessor

     */

    public LobMetadata getLob(boolean isForMapKey) {

        return null;

    }

   

    /**

     * INTERNAL:

     * Return the mapping that this accessor is associated to.

     */

    public DatabaseMapping getMapping(){

        return (m_overrideMapping == null) ? m_mapping : m_overrideMapping;

    }

   

    /**

     * INTERNAL:

     * Return the owning descriptor of this accessor.

     */

    public MetadataDescriptor getOwningDescriptor() {

        return getClassAccessor().getOwningDescriptor();

    }

   

    /**

     * INTERNAL:

     * Return the owning descriptors of this accessor. In most cases this is

     * a single descriptor. Multiples can only exist when dealing with

     * accessors for an embeddable that is shared.

     */

    public List<MetadataDescriptor> getOwningDescriptors() {

        return getClassAccessor().getOwningDescriptors();

    }

   

    /**

     * INTERNAL:

     * Return the map key if this mapping accessor employs one. Those accessors

     * that support it should override this method.

     * @see CollectionAccessor

     * @see ElementCollectionAccessor

     */

    public MapKeyMetadata getMapKey() {

        return null;

    }

   

    /**

     * INTERNAL:

     * Return the map key reference class for this accessor if applicable. It

     * will try to extract a reference class from a generic specification.

     * Parameterized generic keys on a MappedSuperclass will return void.class. 

     * If no generics are used, then it will return void.class. This avoids NPE's

     * when processing JPA converters that can default (Enumerated and Temporal)

     * based on the reference class.

     */

    public MetadataClass getMapKeyReferenceClass() {

        // First check if we are a mapped key map accessor and return its map

        // key class if specified. Otherwise continue on to extract it from

        // a generic specification. We do this to avoid going to the class

        // with is needed for dynamic persistence.

        if (isMappedKeyMapAccessor()) {

            MetadataClass mapKeyClass = ((MappedKeyMapAccessor) this).getMapKeyClass();

            if (mapKeyClass != null && ! mapKeyClass.isVoid()) {

                return mapKeyClass;

            }

        }

       

        if (isMapAccessor()) {

            MetadataClass referenceClass = getAccessibleObject().getMapKeyClass(getDescriptor());

       

            if (referenceClass == null) {

                throw ValidationException.unableToDetermineMapKeyClass(getAttributeName(), getJavaClass());

            }           

       

            // 266912:  Use of parameterized generic types like Map<X,Y>

            // inherits from class<T> in a MappedSuperclass field will cause

            // referencing issues - as in we are unable to determine the correct

            // type for T. A workaround for this is to detect when we are in

            // this state and return a standard top level class. An invalid

            // class will be of the form MetadataClass.m_name="T"

            if (getDescriptor().isMappedSuperclass()) {

                // Determine whether we are directly referencing a class or

                // using a parameterized generic reference by trying to load the

                // class and catching any validationException. If we do not get

                // an exception on getClass then the referenceClass.m_name is

                // valid and should be directly returned

                try {

                    MetadataHelper.getClassForName(referenceClass.getName(), getMetadataFactory().getLoader());

                } catch (ValidationException exception) {

                    // Default to Void for parameterized types

                    // Ideally we would need a MetadataClass.isParameterized() to inform us instead.

                    return getMetadataClass(Void.class);

                }                         

            }

           

            return referenceClass;

        } else {

            return getMetadataClass(void.class);

        }

    }

   

    /**

     * INTERNAL:

     * Return the map key reference class name

     */

    public String getMapKeyReferenceClassName() {

        return getMapKeyReferenceClass().getName();

    }

   

    /**

     * INTERNAL:

     * Return the raw class for this accessor.

     * E.g. For an accessor with a type of java.util.Collection<Employee>, this

     * method will return java.util.Collection. To check for the attribute

     * type we must go through the method calls since some accessors define

     * the attribute type through a target entity specification. Do not access

     * the m_attributeType variable directly in this method.

     */

    public MetadataClass getRawClass() {

        if (hasAttributeType()) {

            // If the class doesn't exist the factory we'll just return a

            // generic MetadataClass

            return getMetadataClass(getAttributeType());

        } else {

            return getAccessibleObject().getRawClass(getDescriptor());

        }

    }

   

    /**

     * INTERNAL:

     * Return the mapping accessors associated with the reference descriptor.

     */

    public Collection<MappingAccessor> getReferenceAccessors() {

        return getReferenceDescriptor().getMappingAccessors();

    }

   

    /**

     * INTERNAL:

     * Return the reference class for this accessor. By default the reference

     * class is the raw class. Some accessors may need to override this

     * method to drill down further. That is, try to extract a reference class

     * from generics.

     */

    public MetadataClass getReferenceClass() {

        return getRawClass();

    }

   

    /**

     * INTERNAL:

     * Attempts to return a reference class from a generic specification. Note,

     * this method may return null.

     */

    public MetadataClass getReferenceClassFromGeneric() {

        return getAccessibleObject().getReferenceClassFromGeneric(getDescriptor());

    }

    /**

     * INTERNAL:

     * Return the reference class name for this accessor.

     */

    public String getReferenceClassName() {

        return getReferenceClass().getName();

    }

   

    /**

     * INTERNAL:

     * Return the reference descriptors table. By default it is the primary

     * key table off the reference descriptor. Subclasses that care to return

     * a different class should override this method.

     * @see DirectCollectionAccessor

     * @see ManyToManyAccessor

     */

    protected DatabaseTable getReferenceDatabaseTable() {

        return getReferenceDescriptor().getPrimaryKeyTable();

    }

   

    /**

     * INTERNAL:

     * Return the reference metadata descriptor for this accessor.

     */

    public MetadataDescriptor getReferenceDescriptor() {

        ClassAccessor accessor = getProject().getAccessor(getReferenceClassName());

       

        if (accessor == null) {

            throw ValidationException.classNotListedInPersistenceUnit(getReferenceClassName());

        }

       

        return accessor.getDescriptor();

    }

    /**

     * INTERNAL:

     * Returns the set method name of a method accessor. Note, this method

     * should not be called when processing field access.

     */

    public String getSetMethodName() {

        return hasAccessMethods() ? getAccessMethods().getSetMethodName() : ((MetadataMethod) getAccessibleObject()).getSetMethodName();

    }

   

    /**

     * INTERNAL:

     * Return the temporal metadata for this accessor.

     * @see DirectAccessor

     * @see CollectionAccessor

     */

    public TemporalMetadata getTemporal(boolean isForMapKey) {

        return null;

    }

   

    /**

     * INTERNAL:

     * Return true if we have an attribute override for this accessor.

     */

    protected boolean hasAttributeOverride(String loggingCtx) {

        if (loggingCtx.equals(MetadataLogger.MAP_KEY_COLUMN)) {

            return getDescriptor().hasAttributeOverrideFor(KEY_DOT_NOTATION + getAttributeName());

        } else if (loggingCtx.equals(MetadataLogger.VALUE_COLUMN)) {

            if (getDescriptor().hasAttributeOverrideFor(VALUE_DOT_NOTATION + getAttributeName())) {

                return true;

            }

        }

           

        return getDescriptor().hasAttributeOverrideFor(getAttributeName());

    }

   

    /**

     * INTERNAL:

     * Those accessors that do not require a separate attribute-type

     * specification for VIRTUAL accessors should override this method. For

     * example, one-to-one and many-to-one will its target-entity.

     * variable-one-to-one will use its target-interface.

     */

    public boolean hasAttributeType() {

        return m_attributeType != null;

    }

   

    /**

     * INTERNAL:

     * Method to check if an annotated element has a Column annotation.

     */

    protected boolean hasColumn() {

        return isAnnotationPresent(JPA_COLUMN);

    }

   

    /**

     * INTERNAL:

     * Method to check if an annotated element has a convert specified. In XML

     * we can restrict where converts can be specified.

     * @see DirectAccessor

     * @see BasicMapAccessor

     * @see ElementCollectionAccessor

     * @see CollectionAccessor

     */

    protected boolean hasConvert(boolean isForMapKey) {

        return isAnnotationPresent(Convert.class);

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor has temporal metadata.

     * @see DirectAccessor

     * @see ElementCollectionAccessor

     * @see CollectionAccessor

     */

    protected boolean hasEnumerated(boolean isForMapKey) {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor has lob metadata.

     * @see DirectAccessor

     * @see ElementCollectionAccessor

     * @see CollectionAccessor

     */

    protected boolean hasLob(boolean isForMapKey) {

        return false;

    }

   

    /**

     * INTERNAL:

     * Method should be overridden by those accessors that accept and use a map

     * key.

     * @see CollectionAccessor

     * @see ElementCollectionAccessor

     * @see BasicMapAccessor

     */

    public boolean hasMapKey() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Method to check if this accessor has a ReturnInsert annotation.

     */

    protected boolean hasReturnInsert() {

        return isAnnotationPresent(ReturnInsert.class);

    }

   

    /**

     * INTERNAL:

     * Method to check if this accessor has a ReturnUpdate annotation.

     */

    protected boolean hasReturnUpdate() {

        return isAnnotationPresent(ReturnUpdate.class);

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor has temporal metadata.

     * @see DirectAccessor

     * @see ElementCollectionAccessor

     * @see CollectionAccessor

     */

    public boolean hasTemporal(boolean isForMapKey) {

        return false;

    }

   

    /**

     * INTERNAL:

     * Init an xml mapping accessor with its necessary components.

     */

    public void initXMLMappingAccessor(ClassAccessor classAccessor) {

        m_classAccessor = classAccessor;

        setEntityMappings(classAccessor.getEntityMappings());

        initXMLAccessor(classAccessor.getDescriptor(), classAccessor.getProject());  

    }

   

    /**

     * INTERNAL:

     */

    @Override

    public void initXMLObject(MetadataAccessibleObject accessibleObject, XMLEntityMappings entityMappings) {

        super.initXMLObject(accessibleObject, entityMappings);

        initXMLObject(m_field, accessibleObject);

    }

   

    /**

     * INTERNAL:

     * Indicates whether the specified annotation is present on the annotated

     * element for this accessor. Method checks against the metadata complete

     * flag.

     */

    @Override

    public boolean isAnnotationPresent(String annotation) {

        return getAccessibleObject().isAnnotationPresent(annotation, getClassAccessor());

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a basic mapping.

     */

    public boolean isBasic() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a basic collection mapping.

     */

    public boolean isBasicCollection() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a basic map mapping.

     */

    public boolean isBasicMap() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor is a derived id class accessor.

     */

    public boolean isDerivedIdClass(){

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a direct collection mapping,

     * which include basic collection, basic map and element collection

     * accessors.

     */

    public boolean isDirectCollection() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents an element collection that

     * contains embeddable objects.

     */

    public boolean isDirectEmbeddableCollection() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a collection accessor.

     */

    public boolean isCollectionAccessor() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents an aggregate mapping.

     */

    public boolean isEmbedded() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents an aggregate id mapping.

     */

    public boolean isEmbeddedId() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this represents an enum type mapping. Will return true

     * if the accessor's reference class is an enum or if enumerated metadata

     * exists.

     */

    protected boolean isEnumerated(MetadataClass referenceClass, boolean isForMapKey) {

        if (hasConvert(isForMapKey)) {

            // If we have an @Enumerated with a @Convert, the @Convert takes

            // precedence and we will ignore the @Enumerated and log a message.

            if (hasEnumerated(isForMapKey)) {

                getLogger().logWarningMessage(MetadataLogger.IGNORE_ENUMERATED, getJavaClass(), getAnnotatedElement());

            }

           

            return false;

        } else {

            return hasEnumerated(isForMapKey) || EnumeratedMetadata.isValidEnumeratedType(referenceClass);

        }

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor is part of the id.

     */

    public boolean isId(){

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a BLOB/CLOB mapping.

     */

    protected boolean isLob(MetadataClass referenceClass, boolean isForMapKey) {

        if (hasConvert(isForMapKey)) {

            // If we have a Lob specified with a Convert, the Convert takes

            // precedence and we will ignore the Lob and log a message.

            if (hasLob(isForMapKey)) {

                getLogger().logWarningMessage(MetadataLogger.IGNORE_LOB, getJavaClass(), getAnnotatedElement());

            }

           

            return false;

        } else {

            return hasLob(isForMapKey);

        }

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a m-m relationship.

     */

    public boolean isManyToMany() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a m-1 relationship.

     */

    public boolean isManyToOne() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor uses a Map.

     */

    public boolean isMapAccessor() {

        return getAccessibleObject().isSupportedMapClass(getRawClass());

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor is a mapped key map accessor. It is a

     * map key accessor for two reasons, it's a map and it does not have

     * a map key specified. NOTE: we can't check for a map key class since

     * one may not have been explicitly specified. In this case, a generic

     * value must be set and we check for one when adding accessors (and in

     * turn set the map key class at that point)

     */

    public boolean isMappedKeyMapAccessor() {

        return MappedKeyMapAccessor.class.isAssignableFrom(getClass()) && isMapAccessor() && ! hasMapKey();

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor is a multitenant id mapping.

     */

    public boolean isMultitenantId() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a 1-m relationship.

     */

    public boolean isOneToMany() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a 1-1 relationship.

     */

    public boolean isOneToOne() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Returns true is the given class is primitive wrapper type.

     */

    protected boolean isPrimitiveWrapperClass(MetadataClass cls) {

        return cls.extendsClass(Number.class) ||

            cls.equals(Boolean.class) ||

            cls.equals(Character.class) ||

            cls.equals(String.class) ||

            cls.extendsClass(java.math.BigInteger.class) ||

            cls.extendsClass(java.math.BigDecimal.class) ||

            cls.extendsClass(java.util.Date.class) ||

            cls.extendsClass(java.util.Calendar.class);

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor has been processed. If there is a mapping

     * set, we have processed this accessor.

     */

    @Override

    public boolean isProcessed() {

        return m_mapping != null;

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor method represents a relationship.

     */

    public boolean isRelationship() {

        return isManyToOne() || isManyToMany() || isOneToMany() || isOneToOne() || isVariableOneToOne();

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a serialized mapping.

     */

    public boolean isSerialized(MetadataClass referenceClass, boolean isForMapKey) {

        if (hasConvert(isForMapKey)) {

            getLogger().logConfigMessage(MetadataLogger.IGNORE_SERIALIZED, getJavaClass(), getAnnotatedElement());

            return false;

        } else {

            return isValidSerializedType(referenceClass);

        }

    }

   

    /**

     * INTERNAL:

     * Return true if this represents a temporal type mapping.

     */

    protected boolean isTemporal(MetadataClass referenceClass, boolean isForMapKey) {

        if (hasConvert(isForMapKey)) {

            // If we have a Temporal specification with a Convert specification,

            // the Convert takes precedence and we will ignore the Temporal and

            // log a message.

            if (hasTemporal(isForMapKey)) {

                getLogger().logWarningMessage(MetadataLogger.IGNORE_TEMPORAL, getJavaClass(), getAnnotatedElement());

            }

           

            return false;

        } else {

            return hasTemporal(isForMapKey) || TemporalMetadata.isValidTemporalType(referenceClass);

        }

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a transient mapping.

     */

    public boolean isTransient() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Returns true if the given class is valid for SerializedObjectMapping.

     */

    protected boolean isValidSerializedType(MetadataClass cls) {

        if (cls.isPrimitive()) {

            return false;

        }

       

        if (isPrimitiveWrapperClass(cls)) {   

            return false;

        }  

       

        if (LobMetadata.isValidLobType(cls)) {

            return false;

        }

       

        if (TemporalMetadata.isValidTemporalType(cls)) {

            return false;

        }

    

        return true;  

    }

   

    /**

     * INTERNAL:

     * Return true if this accessor represents a variable one to one mapping.

     */

    public boolean isVariableOneToOne() {

        return false;

    }

   

    /**

     * INTERNAL:

     * Process an association override for either an embedded object mapping,

     * or a map mapping (element-collection, 1-M and M-M) containing an

     * embeddable object as the value or key.

     * This method should be implemented in those accessors that support

     * association overrides. An exception is thrown otherwise the association

     * is called against an unsupported accessor/relationship.

     */

    protected void processAssociationOverride(AssociationOverrideMetadata associationOverride, EmbeddableMapping embeddableMapping, MetadataDescriptor owningDescriptor) {

        throw ValidationException.invalidEmbeddableAttributeForAssociationOverride(getJavaClass(), getAttributeName(), associationOverride.getName(), associationOverride.getLocation());

    }

   

    /**

     * INTERNAL:

     * Process the association overrides for the given embeddable mapping which

     * is either an embedded or element collection mapping. Association

     * overrides are used to specify different keys to a shared mapping.

     */

    protected void processAssociationOverrides(List<AssociationOverrideMetadata> associationOverrides, EmbeddableMapping embeddableMapping, MetadataDescriptor embeddableDescriptor) {

        // Get the processible map of association overrides. This will take dot

        // notation overrides into consideration (from a sub-entity to a mapped

        // superclass accessor) and merge the lists. Once the map is returned,

        // use the map keys as the attribute name and not the name from the

        // individual association override since they could still contain dot

        // notation names meaning you will not find their respective mapping

        // accessor on the embeddable descriptor.

        Map<String, AssociationOverrideMetadata> mergedAssociationOverrides = getAssociationOverrides(associationOverrides);

       

        for (String attributeName : mergedAssociationOverrides.keySet()) {

            AssociationOverrideMetadata associationOverride = mergedAssociationOverrides.get(attributeName);

            // The getAccessorFor call will take care of any sub dot notation

            // attribute names when looking for the mapping. It will traverse

            // the embeddable chain.

            MappingAccessor mappingAccessor = embeddableDescriptor.getMappingAccessor(attributeName);

           

            if (mappingAccessor == null) {

                throw ValidationException.embeddableAssociationOverrideNotFound(embeddableDescriptor.getJavaClass(), attributeName, getJavaClass(), getAttributeName());

            } else {

                mappingAccessor.processAssociationOverride(associationOverride, embeddableMapping, getOwningDescriptor());

            } 

        }

    }

   

    /**

     * INTERNAL:

     * Process the attribute overrides for the given embedded mapping. Attribute

     * overrides are used to apply the correct field name translations of direct

     * fields. Note an embedded object mapping may be supported as the map key

     * to an element-collection, 1-M and M-M mapping.

     */

    protected void processAttributeOverrides(List<AttributeOverrideMetadata> attributeOverrides, AggregateObjectMapping aggregateObjectMapping, MetadataDescriptor embeddableDescriptor) {

        // Get the processible map of attribute overrides. This will take dot

        // notation overrides into consideration (from a sub-entity to a mapped

        // superclass accessor) and merge the lists. Once the map is returned,

        // use the map keys as the attribute name and not the name from the

        // individual attribute override since they could still contain dot

        // notation names meaning you will not find their respective mapping

        // accessor on the embeddable descriptor.

        Map<String, AttributeOverrideMetadata> mergedAttributeOverrides = getAttributeOverrides(attributeOverrides);

       

        for (String attributeName : mergedAttributeOverrides.keySet()) {

            AttributeOverrideMetadata attributeOverride = mergedAttributeOverrides.get(attributeName);

            // The getMappingForAttributeName call will take care of any sub dot

            // notation attribute names when looking for the mapping. It will

            // traverse the embeddable chain.

            MappingAccessor mappingAccessor = embeddableDescriptor.getMappingAccessor(attributeName);

               

            if (mappingAccessor == null) {

                throw ValidationException.embeddableAttributeOverrideNotFound(embeddableDescriptor.getJavaClass(), attributeName, getJavaClass(), getAttributeName());

            } else if (! mappingAccessor.isBasic()) {

                throw ValidationException.invalidEmbeddableAttributeForAttributeOverride(embeddableDescriptor.getJavaClass(), attributeName, getJavaClass(), getAttributeName());

            } else {

                boolean useDelimitedIdentifier = (embeddableDescriptor.getProject() != null) ? embeddableDescriptor.getProject().useDelimitedIdentifier() : false;

                DatabaseField overrideField = attributeOverride.getColumn().getDatabaseField();

                if (useDelimitedIdentifier){

                    overrideField.setUseDelimiters(useDelimitedIdentifier);

                } else if (embeddableDescriptor.getProject().getShouldForceFieldNamesToUpperCase() && !overrideField.shouldUseDelimiters()) {

                    overrideField.useUpperCaseForComparisons(true);

                }

                addFieldNameTranslation(aggregateObjectMapping, attributeName, overrideField, mappingAccessor);

            }

        }

    }

   

    /**

     * INTERNAL:

     * Set the batch fetch type on the collection mapping.

     */

    protected void processBatchFetch(String batchFetch, ForeignReferenceMapping mapping) {

        if (batchFetch != null) {

            mapping.setBatchFetchType(BatchFetchType.valueOf(batchFetch));

        }  

    }

   

    /**

     * INTERNAL:

     * Process the map metadata if this is a valid map accessor. Will return

     * the map key method name that should be use, null otherwise.

     * @see CollectionAccessor

     * @see ElementCollectionAccessor

     */

    protected void processContainerPolicyAndIndirection(ContainerMapping mapping) {

        if (isMappedKeyMapAccessor()) {

            // If we are a map key map accessor then the following is true:

            // 1 - we implement the mapped key map accessor interface

            // 2 - we are a map accessor

            // 3 - there is no map key metadata specified

            processMapKeyClass(mapping, (MappedKeyMapAccessor) this);

        } else if (isMapAccessor()) {

            // If we are not a mapped key map accessor, but a map accessor,

            // we need a map key metadata object to process. Default one if

            // one is not provided.

            MapKeyMetadata mapKey = getMapKey();

            if (mapKey == null) {