/*
 * The contents of this file are subject to the terms 
 * of the Common Development and Distribution License 
 * (the "License").  You may not use this file except 
 * in compliance with the License.
 * 
 * You can obtain a copy of the license at 
 * glassfish/bootstrap/legal/CDDLv1.0.txt or 
 * https://glassfish.dev.java.net/public/CDDLv1.0.html. 
 * See the License for the specific language governing 
 * permissions and limitations under the License.
 * 
 * When distributing Covered Code, include this CDDL 
 * HEADER in each file and include the License file at 
 * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable, 
 * add the following below this CDDL HEADER, with the 
 * fields enclosed by brackets "[]" replaced with your 
 * own identifying information: Portions Copyright [yyyy] 
 * [name of copyright owner]
 */
// Copyright (c) 1998, 2006, Oracle. All rights reserved.  
package oracle.toplink.essentials.internal.ejb.cmp3.xml;

import java.lang.reflect.Method;
import java.net.URL;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Set;

import oracle.toplink.essentials.ejb.cmp3.EJBQuery;
import oracle.toplink.essentials.exceptions.ValidationException;
import oracle.toplink.essentials.internal.ejb.cmp3.EJBQueryImpl;
import oracle.toplink.essentials.internal.ejb.cmp3.metadata.MetadataAccessor;
import oracle.toplink.essentials.internal.ejb.cmp3.metadata.MetadataDefaultListener;
import oracle.toplink.essentials.internal.ejb.cmp3.metadata.MetadataDescriptor;
import oracle.toplink.essentials.internal.ejb.cmp3.metadata.MetadataHelper;
import oracle.toplink.essentials.internal.ejb.cmp3.metadata.MetadataJoinColumn;
import oracle.toplink.essentials.internal.ejb.cmp3.metadata.MetadataLogger;
import oracle.toplink.essentials.internal.ejb.cmp3.metadata.MetadataProcessor;
import oracle.toplink.essentials.internal.ejb.cmp3.xml.sequencing.Id;
import oracle.toplink.essentials.internal.ejb.cmp3.xml.sequencing.SequenceGenerator;
import oracle.toplink.essentials.internal.ejb.cmp3.xml.sequencing.SequencingProcessor;
import oracle.toplink.essentials.internal.ejb.cmp3.xml.sequencing.TableGenerator;
import oracle.toplink.essentials.internal.helper.DatabaseField;
import oracle.toplink.essentials.internal.helper.DatabaseTable;
import oracle.toplink.essentials.internal.security.PrivilegedAccessController;
import oracle.toplink.essentials.internal.sessions.AbstractSession;
import oracle.toplink.essentials.mappings.AggregateObjectMapping;
import oracle.toplink.essentials.mappings.CollectionMapping;
import oracle.toplink.essentials.mappings.DatabaseMapping;
import oracle.toplink.essentials.mappings.DirectToFieldMapping;
import oracle.toplink.essentials.mappings.ForeignReferenceMapping;
import oracle.toplink.essentials.mappings.ManyToManyMapping;
import oracle.toplink.essentials.queryframework.ColumnResult;
import oracle.toplink.essentials.queryframework.EJBQLPlaceHolderQuery;
import oracle.toplink.essentials.queryframework.EntityResult;
import oracle.toplink.essentials.queryframework.FieldResult;
import oracle.toplink.essentials.sessions.Project;
import oracle.toplink.essentials.sessions.Session;
import oracle.toplink.essentials.queryframework.SQLResultSetMapping; 
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

/**
 * INTERNAL:
 * 
 * Process entity-mappings instance documents, with the end result being a TopLink project.  The 
 * project is handed to this class via TopLink session, and could possibly be partially/fully populated
 * from project XML.  After processing, the project may/may not be fully complete;  if not, the 
 * EJBAnnotationsProcessor will complete the process.  It is assumed here that an entity declaration 
 * does not have to be complete.  Mappings, however, must be fully defined.
 * 
 */
public class EntityMappingsXMLProcessor extends MetadataProcessor {
    // persistence unit default values, set on persistence-unit-default element
    private String m_defaultAccess;
    private String m_defaultCatalog;
    private String m_defaultSchema;
    
    // override values for persistence unit defaults - applies to a given instance document
    // package, catalog and schema can be overridden in entity-mappings element, and 
    // access can be overridden in entity-mappings and entity elements
    private String m_access;
    private String m_catalog;
    private String m_package;
    private String m_schema;
    
    // data members
    private Document m_document;
    private HashMap m_namedQueries;
    private HashMap m_namedNativeQueries;
    private HashMap m_entityListeners;
    private SequencingProcessor m_sequencingProcessor;
    private Project m_project;
    private XPathEngine m_xPathEngine;
    private XMLHelper m_xmlHelper;

    /**
     * The default constructor.
     */
    public EntityMappingsXMLProcessor() {
        this(true);
    }
    
    /**
     * The default constructor.
     */
    public EntityMappingsXMLProcessor(boolean enableLazyForOneToOne) {
        m_enableLazyForOneToOne = enableLazyForOneToOne;
        m_namedQueries = new HashMap();
        m_namedNativeQueries = new HashMap();
        m_entityListeners = new HashMap();
        m_processingContext = ORM_XML;
    }

    /**
     * INTERNAL: 
     * Add EntityListeners to the descriptors of a given TopLink session.
     * 
     * EntityListeners are processed in EntityManagerSetupImpl baseDeploy method, 
     * which is called after the project has been written out, enhanced and read 
     * back in.
     */
	public void addEntityListeners(Session session) {
       for (Iterator it = m_entityListeners.keySet().iterator(); it.hasNext();) {
            String entityClassName = (String) it.next();
            HashMap listenerMap = (HashMap) m_entityListeners.get(entityClassName);
            Class entityClass = MetadataHelper.getClassForName(entityClassName, m_loader);
            XMLDescriptorMetadata dmd = new XMLDescriptorMetadata(MetadataHelper.findDescriptor(session.getProject(), entityClass), entityClass);
            XMLCBListener cbListener;
            Iterator listenIt;
            
    		// handle entity listeners
        	ArrayList listeners = (ArrayList) listenerMap.get(XMLConstants.ENTITY_LISTENERS);
        	for (listenIt = listeners.iterator(); listenIt.hasNext(); ) {
                cbListener = (XMLCBListener) listenIt.next();
                cbListener.initializeCallbackMethods(m_loader);
                dmd.addEntityListenerEventListener(cbListener);
        	}
            
    		// handle callback methods
        	listeners = (ArrayList) listenerMap.get(XMLConstants.CALLBACK_METHODS);
        	for (listenIt = listeners.iterator(); listenIt.hasNext(); ) {
                cbListener = (XMLCBListener) listenIt.next();
                cbListener.initializeCallbackMethods(m_loader);
                dmd.addEntityEventListener(cbListener);
        	}
        } 
	}
	
	/**
     * INTERNAL:
     * If node contains a child tag with name matching eventTag, the associated 
     * method name is stored in the listener for later processing.
     * 
     * @param cbListener 
     * @param node 
     * @param eventTag 
     */
    private void addEventMethodNameToListener(XMLCBListener cbListener, Node node, String eventTag) {
        Node result = m_xPathEngine.selectSingleNode(node, new String[] {eventTag});
        if (result != null) {
        	// process @method-name (required)
            cbListener.addEventMethodName(eventTag, m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_METHOD_NAME}).getNodeValue());
        }
    }
    
	/**
     * INTERNAL:
     * If node contains a child tag with name matching eventTag, the associated 
     * method name is stored in the map for later processing.
     * 
     * @param methodMap
     * @param node 
     * @param eventTag 
     */
    private void addEventMethodNameToMap(HashMap methodMap, Node node, String eventTag) {
        Node result = m_xPathEngine.selectSingleNode(node, new String[] {eventTag});
        if (result != null) {
        	// process @method-name (required)
            methodMap.put(eventTag, m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_METHOD_NAME}).getNodeValue());
        }
    }
    
    /**
     * INTERNAL:
     * Add queries to a given session.  The XMLDescriptorMetadata objects for any
     * entities containing named-query or named-native-query definitions have been
     * flagged and will be processed.  Queries at the entity-mapping level will
     * be processed here as well.
     * 
     * @param session the session to which the processed queries will be added
     */
	public void addNamedQueriesToSession(Session session) {
		HashMap props, hints;
		String queryString;
		
        // for each named-query
        for (Iterator keys = m_namedQueries.keySet().iterator(); keys.hasNext();) {        
            String queryName = (String) keys.next();

            if (session.getQuery(queryName) != null) {
                getLogger().logWarningMessage(MetadataLogger.IGNORE_QUERY, queryName);
                continue;
            }

            try {
            	props = (HashMap) m_namedQueries.get(queryName);
                queryString = (String) props.get(XMLConstants.QUERY);
                hints = (HashMap) props.get(XMLConstants.QUERY_HINT);
                
                // add a new query to the TopLink Session
                session.addEjbqlPlaceHolderQuery(new EJBQLPlaceHolderQuery(queryName, queryString, hints));
            } catch (Exception exception) {
                throw ValidationException.errorProcessingNamedQueryElement(queryName, exception);
            }
        }
        // for each named-native-query
        for (Iterator keys = m_namedNativeQueries.keySet().iterator(); keys.hasNext();) {        
            String queryName = (String) keys.next();
            if (session.getQuery(queryName) != null) {
                getLogger().logWarningMessage(MetadataLogger.IGNORE_QUERY, queryName);
                continue;
            }

            try {
                props = (HashMap) m_namedNativeQueries.get(queryName);
            	queryString = (String) props.get(XMLConstants.QUERY);
                hints = (HashMap) props.get(XMLConstants.QUERY_HINT);

                // result-class (takes precidence)
                if (props.containsKey(XMLConstants.ATT_RESULT_CLASS)) {
                    Class resultClass = MetadataHelper.getClassForName(((String) props.get(XMLConstants.ATT_RESULT_CLASS)), m_loader);
                    if (resultClass != void.class) {
                        // add a new query to the TopLink Session
                        session.addQuery(queryName, EJBQueryImpl.buildSQLDatabaseQuery(resultClass, queryString, hints));
                        continue;
                    }
                }
                
                // result-set-mapping
                if (props.containsKey(XMLConstants.ATT_RESULT_SET_MAPPING)) {
                    // add a new query to the TopLink Session
                    session.addQuery(queryName, EJBQueryImpl.buildSQLDatabaseQuery((String) props.get(XMLConstants.ATT_RESULT_SET_MAPPING), queryString, hints));
                    continue;
                }
                
                // at this point we need to set default query values on the session
                session.addQuery(queryName, EJBQueryImpl.buildSQLDatabaseQuery(queryString, hints));
            } catch (Exception exception) {
                throw ValidationException.errorProcessingNamedQueryElement(queryName, exception);
            }
        }
	}

    /**
     * INTERNAL:
     * The class name of each node in the node list will be added to the provided collection.
     * 
     * @param xmlDoc 
     * @param xPath 
     * @param defaultPkg
     */
    private static Set buildClassSetForNodeList(Document xmlDoc, String xPath, String defaultPkg) {
    	HashSet classNameSet = new HashSet();
        XPathEngine xPathEngine = XPathEngine.getInstance();
        
    	NodeList nodes = xPathEngine.selectNodes(xmlDoc, new String[] {XMLConstants.ENTITY_MAPPINGS, xPath});
        for (int i=0; i<nodes.getLength(); i++) {
            // process @class (required)
            classNameSet.add(XMLHelper.getFullyQualifiedClassName(xPathEngine.selectSingleNode(nodes.item(i), new String[] {XMLConstants.ATT_CLASS}).getNodeValue(), defaultPkg));
        }
        return classNameSet;
    }
    
    /**
     * INTERNAL:
     * Return a set of class names for each entity, embeddable, or mapped-superclass found 
     * in the xml descriptor instance document.
     * 
     * @param xmlDocumentURL 
     * @param loader 
     * @return 
     */
    public static Set buildClassSet(URL xmlDocumentURL, ClassLoader loader) {
        XPathEngine xPathEngine = XPathEngine.getInstance();
        HashSet classSet = new HashSet();
        Document xmlDoc = XMLHelper.parseDocument(xmlDocumentURL, loader);
        String defaultPkg = "";
        Node node;

        // process package
        if ((node = xPathEngine.selectSingleNode(xmlDoc, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.PACKAGE, XMLConstants.TEXT})) != null) {
            defaultPkg = node.getNodeValue();
        }

        // handle entities, embeddables and mapped-superclasses
        classSet.addAll(buildClassSetForNodeList(xmlDoc, XMLConstants.ENTITY, defaultPkg));
        classSet.addAll(buildClassSetForNodeList(xmlDoc, XMLConstants.EMBEDDABLE, defaultPkg));
        classSet.addAll(buildClassSetForNodeList(xmlDoc, XMLConstants.MAPPED_SUPERCLASS, defaultPkg));
        
        return classSet;
    }
    
    /**
     * INTERNAL:
     * 
     * @param attributeNode
     * @param dmd
     * @return
     */
    private XMLAccessor createAccessor(Node attributeNode, XMLDescriptorMetadata dmd) {
		// process @name (required)
        String attributeName = m_xPathEngine.selectSingleNode(attributeNode, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
		XMLAccessor accessor = new XMLAccessor(attributeName, this, dmd, attributeNode);
        return accessor;
    }

    /**
     * INTERNAL:
     * Process entity listeners.  A default CBListener will be created for each listener.
     * 
     * @param listenerClassName 
     * @param entityClassName 
     * @param eventMethods
     * @param entityListenerList 
     */
    private void createDefaultCBListener(String listenerClassName, String entityClassName, HashMap eventMethods, ArrayList entityListenerList) {
        MetadataDefaultListener listener = new MetadataDefaultListener(listenerClassName, entityClassName);
        listener.getEventMethodNames().putAll(eventMethods);
        entityListenerList.add(listener);
    }
    
    /**
     * INTERNAL:
     * Process entity listeners.  A CBListener will be created for each listener.
     * 
     * @param node 
     * @param xPath 
     * @param entityClassName 
     * @param entityListenerList 
     */
    private void createCBListeners(Node node, String[] xPath, String entityClassName, ArrayList entityListenerList) {
        // process listeners
        NodeList listenerNodes = m_xPathEngine.selectNodes(node, xPath);
        if (listenerNodes.getLength() > 0) {
            // for each listener...
            for (int i=0; i<listenerNodes.getLength(); i++) {
                Node listenerNode = listenerNodes.item(i);
                
                // process @class (required)
                String listenerClassName = m_xmlHelper.getClassNameForNode(listenerNode);
                
                XMLCBListener listener = new XMLCBListener(listenerClassName, entityClassName);
                processEvents(listener, listenerNode);
                entityListenerList.add(listener);
            }
        }
    }
    
    /**
     * INTERNAL:
     * Create and populate a SQLResultSetMapping.  This method assumes that 'node'
     * is a valid sql-result-set-mapping node, i.e. it is non-null and contains child
     * nodes.
     * 
     * @param node a sql-result-set-mapping node from either an entity or entity-mapping
     * element.
     * @return a populated SQLResutlSetMapping mapping
     */
    private SQLResultSetMapping createSQLResultSetMapping(Node node) {
        // process @name (required)
        SQLResultSetMapping mapping = new SQLResultSetMapping(m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_NAME}).getNodeValue());

        // process entity-results
        NodeList entityResultNodes = m_xPathEngine.selectNodes(node, new String[] {XMLConstants.ENTITY_RESULT});
        if (entityResultNodes != null) {
            for (int j=0; j<entityResultNodes.getLength();j++) {
                Node erNode = entityResultNodes.item(j);

                // process @entity-class (required)
                Node result = m_xPathEngine.selectSingleNode(erNode, new String[] {XMLConstants.ATT_ENTITY_CLASS});
                Class entityClass = MetadataHelper.getClassForName(result.getNodeValue(), m_loader);
                EntityResult eResult = new EntityResult(entityClass.getName());
                
                // process @discriminator-column
                result = m_xPathEngine.selectSingleNode(erNode, new String[] {XMLConstants.ATT_DISCRIMINATOR_COLUMN});
                if (result != null) {
                    eResult.setDiscriminatorColumn(result.getNodeValue());
                }
                
                // process field-results
                NodeList fieldResultNodes = m_xPathEngine.selectNodes(erNode, new String[] {XMLConstants.FIELD_RESULT});
                if (fieldResultNodes != null) {
                    for (int k=0; k<fieldResultNodes.getLength();k++) {
                        Node frNode = fieldResultNodes.item(k);
                
                        // process @name (required)
                        String name = m_xPathEngine.selectSingleNode(frNode, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
                        // process @column (required)
                        String column = m_xPathEngine.selectSingleNode(frNode, new String[] {XMLConstants.ATT_COLUMN}).getNodeValue();
                        
                        eResult.addFieldResult(new FieldResult(name, column));
                    }
                }
                mapping.addResult(eResult);
            }
        }
        // process column-results
        NodeList columnResultList = m_xPathEngine.selectNodes(node, new String[] {XMLConstants.COLUMN_RESULT});
        if (columnResultList != null) {
            for (int j=0;j<columnResultList.getLength();j++) {
                // process @name (required)
                mapping.addResult(new ColumnResult(m_xPathEngine.selectSingleNode(columnResultList.item(j), new String[] {XMLConstants.ATT_NAME}).getNodeValue()));
            }
        }

        return mapping;
    }

    /**
     * INTERNAL:
	 * Lazily create a metadata/descriptor for any given class. 
     */
	public XMLDescriptorMetadata getMetadataDescriptor(Class cls) {
		XMLDescriptorMetadata dmd = (XMLDescriptorMetadata) getDescriptorMetadataMap().get(cls);
		if (dmd == null) {
            if (MetadataHelper.descriptorAlreadyExists(m_session.getProject(), cls)) {
                // wrap the existing descriptor into an XMLDescriptorMetadata 
                dmd = new XMLDescriptorMetadata(MetadataHelper.findDescriptor(m_session.getProject(),cls), cls, m_xmlHelper);
            } else {
                // create a new descriptor metadata and add it to the project
                dmd = new XMLDescriptorMetadata(cls, m_xmlHelper);
                m_session.getProject().addDescriptor(dmd.getDescriptor());
            }
            getDescriptorMetadataMap().put(cls, dmd);
        } else {
        	// make sure the descriptor gets added to the project - descriptor metadata 
        	// objects created in processPersistenceUnitDefaults will not have their 
        	// descriptors added to the project initially...
            if (!MetadataHelper.descriptorAlreadyExists(m_session.getProject(), cls)) {
            	m_session.getProject().addDescriptor(dmd.getDescriptor());
    			dmd.setHelper(m_xmlHelper);
            }
        }
        return dmd;
	}
	
	/**
     * INTERNAL:
     * Return the map containing descriptor metadata objects for any processed
     * entities.  The map is keyed on the entity java class.
     * 
     * @return HashMap of descriptor metadata objects keyed on java class
     */
    public HashMap getDescriptorMetadataMap() {
        if (m_metadataDescriptors == null) {
        	m_metadataDescriptors = new HashMap();
        }
        
        return m_metadataDescriptors;
    }
    
    /**
     * INTERNAL:
     * 
     * @param accessor
     * @return
     */
    protected Object[] getCascadeTypes(XMLAccessor accessor) {
    	HashSet cascadeVals = new HashSet();
        if (accessor.hasCascade()) {
        	NodeList cascadeNodes = accessor.getCascade();
			for (int i=0; i<cascadeNodes.getLength(); i++) {
				cascadeVals.add(cascadeNodes.item(i).getLocalName());
            }
        }
        return cascadeVals.toArray();
    }

    /**
     * INTERNAL:
     * Helper method to return a field name from a candidate field name and a 
     * default field name.
     * 
     * @param candidateName 
     * @param defaultName 
     * @param context 
     * @param javaClass 
     * @return 
     */
	protected String getFieldName(String candidateName, String defaultName, String context, Class javaClass) {
		// check if a candidate was specified otherwise use the default
        if (candidateName != null && !candidateName.equals("")) {
            return candidateName;
        }
        
        // log the defaulting field name based on the given context
        getLogger().logConfigMessage(context, javaClass, defaultName);
        return defaultName;
	}
    
	/**
	 * INTERNAL:
	 * @return
	 */
	XMLHelper getHelper() {
		return m_xmlHelper;
	}

    /**
     * INTERNAL:
     * Determine the appropriate type of hintValue based on the hintName, and return
     * the typed value.  Expressions and Calls will not be supported in XML. Warnings 
     * will be thrown for these and any other unsupported values.  
     * 
     * Hints - types:
     * 
     * 	fetchSize - Integer
     * 	referenceClass - class
     * 	cacheusage - Integer
     * 	refresh - Boolean
     * 	lockMode - Integer
     * 	expression - TopLink Expression (not supported)
     * 	timeout - Integer
     * 
     * @param hintName name of hint
     * @param hintValue value of hint
     * @param queryName used for logging warning messages
     * @param entityClass the ownign entity class - used for logging warnings
     * @return appropriate typed value, or null if the type cannot be determined
     */
    private Object getTypedHintValue(String hintName, String hintValue, String queryName, String entityClass) {
        try {
            if (hintName.equals(EJBQuery.REFERENCE_CLASS)) {
                return MetadataHelper.getClassForName(hintValue, m_loader);
            } else if (hintName.equals(EJBQuery.CACHE_USAGE) || hintName.equals(EJBQuery.CASCADE_LEVEL)) {
                return Integer.valueOf(hintValue);
            } else if (hintName.equals(EJBQuery.REFRESH)) {
                return Boolean.valueOf(hintValue);
            } else if (hintName.equals(EJBQuery.LOCK_MODE)) {
                return Short.valueOf(hintValue);
            } else if (hintName.equals(EJBQuery.EXPRESSION) || hintName.equals(EJBQuery.CALL)) {
                // expression and call are not supported in XML
                getLogger().logWarningMessage(EntityMappingsXMLLogger.IGNORE_QUERY_HINT_UNSUPPORTED_TYPE, hintName, queryName, entityClass);
                return null;
            }
        } catch (ClassCastException exception) {
            // fall through, throw a warning, and return null
        }
        
        getLogger().logWarningMessage(EntityMappingsXMLLogger.IGNORE_QUERY_HINT_UNKNOWN_TYPE, hintName, queryName, entityClass);
        return null;
    }
	
    /** 
     * INTERNAL:
	 * Return the logger used by this processor.
	 */
	public EntityMappingsXMLLogger getLogger() {
		return (EntityMappingsXMLLogger) m_logger;
    }
    
    /**
     * INTERNAL:
	 * Method to return the primary key fields for the given descriptor
     * metadata.
     */
    protected List getPrimaryKeyFields(XMLDescriptorMetadata dmd) {
        List primaryKeyFields = dmd.getPrimaryKeyFields();
        
        // if this is an inheritance subclass, get the primary key fields from the parent
        if (primaryKeyFields.isEmpty() && dmd.isInheritanceSubclass()) {
            primaryKeyFields = getMetadataDescriptor(m_xmlHelper.locateRootEntity(dmd.getJavaClass())).getPrimaryKeyFields();
        }
        
        return primaryKeyFields;
    }
    
    /**
     * INTERNAL:
     * Returns an array primary key join column sub-nodes for a given
     * node.
     * 
     * @param node
     * @return
     */
    protected Object[] getPrimaryKeyJoinColumns(Node node) {
        Object[] pkJoinCols = {};
    	// look for primary-key-join-column(s) elements
        NodeList primaryKeyJoinColumns = m_xPathEngine.selectNodes(node, new String[] {XMLConstants.PK_JOIN_COLUMN});
        if (primaryKeyJoinColumns != null) {
        	pkJoinCols = new Object[primaryKeyJoinColumns.getLength()];
        	for (int i=0; i<primaryKeyJoinColumns.getLength(); i++) {
        		pkJoinCols[i] = primaryKeyJoinColumns.item(i);
        	}
        }
    	return pkJoinCols;
    }
    
    /**
     * INTERNAL:
     * Method to return the name of the join table.
     * 
     * @param joinTableNode
     * @param source
     * @param targetName
     * @param attributeName
     * @return
     */
    private DatabaseTable getRelationTable(XMLAccessor accessor) {
        DatabaseTable relationTable;
        Node joinTableNode = accessor.getJoinTableNode();
        
        if (joinTableNode != null) {
            String tableName = "";
            String catalogName = m_catalog;
            String schemaName = m_schema;

            Node attr;
            // process @name
            if ((attr = m_xPathEngine.selectSingleNode(joinTableNode, new String[] {XMLConstants.ATT_NAME})) != null) {
                tableName = attr.getNodeValue();
            }
            // process @schema
            if ((attr = m_xPathEngine.selectSingleNode(joinTableNode, new String[] {XMLConstants.ATT_SCHEMA})) != null) {
                schemaName = attr.getNodeValue();
            }
            // process @catalog
            if ((attr = m_xPathEngine.selectSingleNode(joinTableNode, new String[] {XMLConstants.ATT_CATALOG})) != null) {
                catalogName = attr.getNodeValue();
            }
            
    	    relationTable = buildJoinTable(tableName, catalogName, schemaName, accessor);
            
            // process unique-constraints
            processUniqueConstraints(getUniqueConstraints(joinTableNode), relationTable);
        } else {
    	    relationTable = buildJoinTable(accessor);
        }
        
        return relationTable;
    }
     
   /**
     * INTERNAL:
     * Process the table information contained within a table-generator type
     * 
     * @param generatorNode 
     * @return 
     */
    private TableInfo getTableInfo(Node generatorNode) {
        // set default values
        String tableName = "";
        String catalogName = m_catalog;
        String schemaName = m_schema;
        Object[] uniqueConstraints = {};
        TableInfo tableInfo;

        if (generatorNode != null) {
            Node attr;
            // process @table
            if ((attr = m_xPathEngine.selectSingleNode(generatorNode, new String[] {XMLConstants.ATT_TABLE})) != null) {
                tableName = attr.getNodeValue();
            }
            // process @schema
            if ((attr = m_xPathEngine.selectSingleNode(generatorNode, new String[] {XMLConstants.ATT_SCHEMA})) != null) {
                schemaName = attr.getNodeValue();
            }
            // process @catalog
            if ((attr = m_xPathEngine.selectSingleNode(generatorNode, new String[] {XMLConstants.ATT_CATALOG})) != null) {
                catalogName = attr.getNodeValue();
            }
            // process unique-constraint
            uniqueConstraints = getUniqueConstraints(generatorNode);
            
            // TODO: change this to use Object[] if possible
            ArrayList constraintsList = new ArrayList();
            for (int i=0; i<uniqueConstraints.length; i++) {
            	constraintsList.add(uniqueConstraints[i]);
            }

            tableInfo = new TableInfo(tableName, catalogName, schemaName, constraintsList);
        } else {
            tableInfo = new TableInfo();
            tableInfo.isSpecified(false);
        }
        
        return tableInfo;
    }
    
    /**
     * INTERNAL:
     * Initialize data members - this is done such that subsequent calls to the
     * processor don't require a new instance of the class.  A DOM is also 
     * constructed from the instance document indicated by xmlDocumentURL.
     * 
     * @param session TopLink session containing a TopLink project to which persistence 
     * information (contained within the provided persistence ORM instance document)
     * @param xmlDocumentURL the URL of the instance document to be processed
     * @param classLoader the class loader to be used
     */
    private void init(AbstractSession session, URL xmlDocumentURL) {
        // initialize data members
        m_project = session.getProject();
        m_xPathEngine = XPathEngine.getInstance();
        m_session = session;
        m_sequencingProcessor = new SequencingProcessor();
        m_logger = new EntityMappingsXMLLogger(session);
        m_xmlHelper = new XMLHelper(xmlDocumentURL, m_loader);
        m_relatedEntities = new HashSet();
        
        // set access, schema and catalog to persistence unit defaults
        m_access = m_defaultAccess;
        m_schema = m_defaultSchema;
        m_catalog = m_defaultCatalog;
        m_package = m_xmlHelper.getPackage();
        
        // create a DOM from the instance document
        m_document = m_xmlHelper.getDocument();
    }

    /**
     * INTERNAL:
     * Process the unique-constraints for a given table node.
     * 
     * @param tableNode 
     * @return an array of DatabaseFields - one for each column-name
     */
    private Object[] getUniqueConstraints(Node tableNode) {
        Object[] uniqueConstraints = {};
        
        NodeList constraints = m_xPathEngine.selectNodes(tableNode, new String[] {XMLConstants.UNIQUE_CONSTRAINTS});
        if (constraints != null) {
        	uniqueConstraints = new Object[constraints.getLength()];
            // for each unique-constraint...
            for (int j=0; j<constraints.getLength(); j++) {
                Node constraintNode = constraints.item(j);
                // process column-name(s)
                NodeList columnNameNodeList = m_xPathEngine.selectNodes(constraintNode, new String[] {XMLConstants.COLUMN_NAME});
                if (columnNameNodeList != null) {
                    // for each column-name
                    for (int k=0; k<columnNameNodeList.getLength(); k++) {
                        String columnName = columnNameNodeList.item(k).getNodeValue();
                        if (columnName != null && !columnName.equals("")) {
                            uniqueConstraints[j] = columnName;
                        }
                    }
                }
            }
        }
        return uniqueConstraints;   
    }
    
    /**
     * INTERNAL:
     */
	public boolean hasPrimaryKeyJoinColumn(Node node) {
		return m_xPathEngine.selectNodes(node, new String[] {XMLConstants.PK_JOIN_COLUMN}).getLength()>0;
	}    
	
    /**
     * INTERNAL:
     * Locate a node in the DOM tree for a given class.  
     * 
     * @param className the name of the class to search the DOM for
     * @param searchString the node name to search for, i.e. ENTITY or MAPPED_SUPERCLASS
     * @return 
     */
	public Node locateNode(Class cls, String searchString) {
		return m_xmlHelper.locateNode(cls, searchString);
	}
    	
    /**
     * INTERNAL:
     * Process the attributes of an entity or embeddable.
     * 
     * @param dmd
     */
    protected void processAccessors(MetadataDescriptor dmd) {
    	processAttributes((XMLDescriptorMetadata) dmd, m_xmlHelper.locateNode(dmd.getJavaClass()));
    }
    
    /**
     * INTERNAL:
     * Satisfy the abstract method declaration in MetadataProcessor.
     */
    protected void processAssociationOverrides(MetadataAccessor accessor, AggregateObjectMapping mapping) {
        return;
    }
    
    /**
     * INTERNAL:
     * Process association-override info.
     * 
     * @param dmd
     * @param entityNode
     */
    protected void processAssociationOverrides(XMLDescriptorMetadata dmd, Node entityNode) {
    	NodeList nodes = m_xPathEngine.selectNodes(entityNode, new String[] {XMLConstants.ASSOCIATION_OVERRIDE});
    	if (nodes != null) {
    		for (int i=0; i<nodes.getLength(); i++) {
    			Node overrideNode = nodes.item(i);
    			// process @name (required)
    			String name = m_xPathEngine.selectSingleNode(overrideNode, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
    			
    	        // process join-columns
    	        NodeList jCols = m_xPathEngine.selectNodes(overrideNode, new String[] {XMLConstants.JOIN_COLUMN});
    	        if (jCols != null && jCols.getLength()>0) {
                    dmd.addAssociationOverride(name, new Object[] {jCols});
    	        }            	
    		}
    	}
    }
    
    /**
     * INTERNAL:
     * Process the attributes of an entity, embeddable or mapped-superclass.
     * 
     * @param dmd
     */
    protected void processAccessors(Class cls, XMLDescriptorMetadata dmd) {
    	processAttributes(dmd, m_xmlHelper.locateNode(cls));
    }

    /**
     * INTERNAL:
     * @param accessor
     * @param mapping
     */
    protected void processAttributeOverrides(MetadataAccessor metadataAccessor, AggregateObjectMapping mapping) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	if (accessor.hasAttributeOverrides()) {
    		NodeList overrides = accessor.getAttributeOverrideNodes();
    		for (int i=0; i<overrides.getLength(); i++) {
    			Node overrideNode = overrides.item(i);
                // process @name (required)
                String overrideName = m_xPathEngine.selectSingleNode(overrideNode, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
                // process column
                Node columnNode = m_xPathEngine.selectSingleNode(overrideNode, new String[] {XMLConstants.COLUMN});
                processAttributeOverride(overrideName, columnNode, accessor, mapping);
    		}
    	}
    }
    
    /**
     * INTERNAL:
	 * Process the attribute overrides for an entity that inherits from an 
     * abstract entity.  These overrides are at the entity level, and not the
     * attribute level.
     * 
     * @param dmd
	 */
    protected void processAttributeOverrides(XMLDescriptorMetadata dmd) {
    	processAttributeOverrides(dmd.getJavaClass(), dmd);
    }

    /**
     * INTERNAL:
	 * Process the attribute overrides for an entity that inherits from an 
     * abstract entity.  These overrides are at the entity level, and not the
     * attribute level.
     * 
     * @param dmd
	 */
    protected void processAttributeOverrides(Class cls, XMLDescriptorMetadata dmd) {
        Node entityNode = m_xmlHelper.locateNodeForEntity(cls);

        NodeList nodes = m_xPathEngine.selectNodes(entityNode, new String[] {XMLConstants.ATTRIBUTE_OVERRIDE});
        if (nodes != null) {
            for (int i=0; i<nodes.getLength(); i++) {
                Node node = nodes.item(i);
                
                // process @name (required)
                String attributeName = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
                
                // process column
                Node columnNode = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.COLUMN});
                if (columnNode != null) {
                    DatabaseField dbField = processColumn(columnNode, attributeName, dmd, dmd.getJavaClass());
                    dmd.addAttributeOverride(attributeName, dbField);
                } 
            }
        }
    }
    
    /**
     * INTERNAL:
     * Method to init a collection mapping from a one-to-many.
     */
    protected void populateCollectionMapping(CollectionMapping mapping, Object oneToManyNode, MetadataAccessor metadataAccessor) {
    	Node oneToMany = (Node) oneToManyNode;
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
        
        // Process the annotation specifics if there is one (may have been
        // defaulted). These are our defaults otherwise.
        boolean usesIndirection = false;
        Class targetEntity = void.class;
        Object[] cascade = {};
		
        if (oneToMany != null) {
            // OneToMany.fetch()
            usesIndirection = accessor.getFetchType().equals(XMLConstants.LAZY);
            // OneToMany.targetEntity()
            targetEntity = accessor.getTargetEntity();
            // OneToMany.cascade()
            cascade = getCascadeTypes(accessor);
        }
		
        populateCollectionMapping(mapping, accessor, usesIndirection, targetEntity, cascade);
    }
    
    
    /**
     * INTERNAL:
     * @param generatedValueNode
     * @param accessor
     * @param field
     * @param dmd
     * 
     */
    protected void preProcessGeneratedValue(Object generatedValueNode, MetadataAccessor accessor, DatabaseField field, MetadataDescriptor dmd) {
        String strategy = AUTO;
        String generator = "";
    	Node result;

    	// process @strategy
        if ((result = m_xPathEngine.selectSingleNode((Node) generatedValueNode, new String[] {XMLConstants.ATT_STRATEGY})) != null) {
            strategy = result.getNodeValue();
        }
        // process @generator
        if ((result = m_xPathEngine.selectSingleNode((Node) generatedValueNode, new String[] {XMLConstants.ATT_GENERATOR})) != null) {
            generator = result.getNodeValue();
        }

        // TODO: should call preProcessGeneratedValue()...
        // pre-process the id for the sequencing
        m_sequencingProcessor.preProcessId(new Id(strategy, generator), field, dmd.getDescriptor());
    }

    /**
     * INTERNAL:
	 * Pre-process sequencing.  Gather the necessary info. The real sequencing 
     * setup is performed after all the sequencing-related info on all classes 
     * is preprocessed.
     * 
     * @param node either an entity or entity-mappings node
     */
    private void preProcessSequenceGenerator(Node node) {
        int initialValue = 0;
        int allocationSize = 50;

        // process @name (required)
        String name = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
        
        // process @sequence-name
        String sequenceName = name;
        Node result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_SEQUENCE_NAME});
        if (result != null) {
            sequenceName = result.getNodeValue();
        }
        // process @initial-value
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_INITIAL_VALUE})) != null) {
            initialValue = Integer.parseInt(result.getNodeValue());
        }
        // process @allocation-size
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_ALLOCATION_SIZE})) != null) {
            allocationSize = Integer.parseInt(result.getNodeValue());
        }

        m_sequencingProcessor.preProcessSequenceGenerator(new SequenceGenerator(name, sequenceName, initialValue, allocationSize));
    }
    
    /**
     * INTERNAL:
     * Pre-process any sequencing. Gather the necessary info. The real sequencing setup 
     * is performed after all the sequencing-related info on all classes is pre-processed.
     */
    protected void preProcessSequencing(MetadataAccessor metadataAccessor) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	Node generator;
    	// process table-generator
        if ((generator = accessor.getTableGeneratorNode()) != null) {
            preProcessTableGenerator(generator);
        }
        // process sequence-generator
        if ((generator = accessor.getSequenceGeneratorNode()) != null) {
            preProcessSequenceGenerator(generator);
        }
    } 
    
    /**
     * INTERNAL:
	 * Pre-process sequencing.  Gather the necessary info. The real sequencing 
     * setup is performed after all the sequencing-related info on all classes 
     * is pre-processed.
     * 
     * @param node
     */
    private void preProcessTableGenerator(Node node) {
        // set defaults
        String pkColumnName = "";
        String valueColumnName = "";
        String pkColumnValue = "";
        int initialValue = 0;
        int allocationSize = 50;
        Node result;

        // process @name (required)    
        String name = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
        
        // process @pk-column-name
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_PK_COLUMN_NAME})) != null) {
            pkColumnName = result.getNodeValue();
        }
        // process @value-column-name
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_VALUE_COLUMN_NAME})) != null) {
            valueColumnName = result.getNodeValue();
        }
        // process @pk-column-value
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_PK_COLUMN_VALUE})) != null) {
            pkColumnValue = result.getNodeValue();
        }
        // process @initial-value
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_INITIAL_VALUE})) != null) {
            initialValue = Integer.parseInt(result.getNodeValue());
        }
        // process @allocation-size
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_ALLOCATION_SIZE})) != null) {
            allocationSize = Integer.parseInt(result.getNodeValue());
        }

        TableInfo tableInfo = getTableInfo(node);        

        m_sequencingProcessor.preProcessTableGenerator(new TableGenerator(name, pkColumnName, valueColumnName, pkColumnValue, tableInfo, initialValue, allocationSize));
    }
   
    /**
     * INTERNAL:
     * Process attributes.
     * 
     * @param dmd the XMLDescriptorMetadata object of the owning entity
     * @param node the DOM node representing the owning entity
     */
    private void processAttributes(XMLDescriptorMetadata dmd, Node node) {
        NodeList attributeNodes = m_xPathEngine.selectNodes(node, new String[] {XMLConstants.ATTRIBUTES, XMLConstants.ALL_CHILDREN});
        if (attributeNodes != null) {
	        // for each attribute...
	        for (int i=0; i<attributeNodes.getLength(); i++) {
	        	processAccessor(createAccessor(attributeNodes.item(i), dmd));
	        }
        }
    }

    /**
     * INTERNAL:
     * Process a basic element.
     */
    protected void processBasic(MetadataAccessor metadataAccessor, DirectToFieldMapping mapping) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	if (accessor.isBasic()) {
	    	// handle @fetch
	    	if (accessor.getFetchType().equals(XMLConstants.LAZY)) {
	            getLogger().logWarningMessage(MetadataLogger.IGNORE_BASIC_FETCH_LAZY, accessor);
	        }
	        // handle @optional
	    	mapping.setIsOptional(accessor.isOptional());
    	}
    }
    
    /**
     * INTERNAL:
     * Process the cascade type on a mapping.
     * 
     * @param cascadeTypes
     * @param mapping
     */
    protected void processCascadeType(MetadataAccessor accessor, Object[] cTypes, ForeignReferenceMapping mapping) {
        for (int i=0; i<cTypes.length; i++) {
            setCascadeType((String) cTypes[i], mapping);
        }
        // apply the persistence unit default cascade-persist if necessary
        if (accessor.getMetadataDescriptor().isCascadePersistSet() && !mapping.isCascadePersist()) {
        	setCascadeType(XMLConstants.CASCADE_PERSIST, mapping);
        }
    }
    
    /**
     * INTERNAL:
     * @param columnNode
     * @param annotatedElement
     * @param attributeName
     * @param dmd
     * @return
     */
    protected DatabaseField processColumn(Object columnNode, Object annotatedElement, String attributeName, MetadataDescriptor dmd) {
    	if (columnNode != null) {
        	return processColumn((Node) columnNode, attributeName, (XMLDescriptorMetadata) dmd, annotatedElement);
    	}
    	// set defaults
    	return processColumnDefaults(attributeName, dmd, annotatedElement);
    }
    
    /**
     * INTERNAL:
     * @param metadataAccessor
     * @return
     */
    protected DatabaseField processColumn(MetadataAccessor metadataAccessor) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	if (accessor.hasColumn()) {
    		return processColumn(accessor.getColumnNode(), accessor.getAttributeName(), accessor.getMetadataDescriptor(), accessor.getAnnotatedElement());
    	}
    	// set defaults
    	return processColumnDefaults(accessor);
    }
    
    /**
     * INTERNAL:
     * Process a column in a DatabaseField and return it.
     * 
     * @param columnNode
     * @param attributeName
     * @param dmd
     * @param element
     */
    private DatabaseField processColumn(Node columnNode, String attributeName, XMLDescriptorMetadata dmd, Object element) {
        String fieldName = "";
        String columnDefinition = "";
        String tableName = "";
        boolean isUnique = false;
        boolean isNullable = true;
        boolean isInsertable = true;
        boolean isUpdatable = true;
        int length = 255;
        int precision = 0;
        int scale = 0;
        Node result;
        
        // process @name
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_NAME})) != null) {
            fieldName = result.getNodeValue();
        }
        // process @table
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_TABLE})) != null) {
            tableName = result.getNodeValue();
        }
        // process @insertable
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_INSERTABLE})) != null) {
            isInsertable = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @updatable
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_UPDATABLE})) != null) {
            isUpdatable = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @unique
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_UNIQUE})) != null) {
            isUnique = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @nullable
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_NULLABLE})) != null) {
            isNullable = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @column-definition
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_COLUMN_DEFINITION})) != null) {
            columnDefinition = result.getNodeValue();
        }
        // process @length
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_LENGTH})) != null) {
            length = Integer.parseInt(result.getNodeValue());
        }
        // process @precision
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_PRECISION})) != null) {
            precision = Integer.parseInt(result.getNodeValue());
        }
        // process @scale
        if ((result = m_xPathEngine.selectSingleNode(columnNode, new String[] {XMLConstants.ATT_SCALE})) != null) {
            scale = Integer.parseInt(result.getNodeValue());
        }

        return processColumn(attributeName, dmd, fieldName, columnDefinition, tableName, isUnique, isNullable, isInsertable, isUpdatable, length, precision, scale, element);
	}

    /**
     * INTERNAL:
     * Process discriminator-column information.
     * 
     * @param dmd 
     */
    private void processDiscriminatorColumn(XMLDescriptorMetadata dmd, Node entityNode) {
        String discriminatorType = STRING;
        String columnName = "";
        String columnDefinition = "";
        int length = 31;

        Node result;
        if ((result = m_xPathEngine.selectSingleNode(entityNode, new String[] {XMLConstants.DISCRIMINATOR_COLUMN})) != null) {
            Node discriminatorResult;
                            
            // process @discriminator-type
            if ((discriminatorResult = m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_DISCRIMINATOR_TYPE})) != null) {
               // TODO:  what do we do with discriminator-type?
               discriminatorType = discriminatorResult.getNodeValue();
            }
            // process @name
            if ((discriminatorResult = m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_NAME})) != null) {
                columnName = discriminatorResult.getNodeValue();
            }
            // process @column-definition
            if ((discriminatorResult = m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_COLUMN_DEFINITION})) != null) {
                columnDefinition = discriminatorResult.getNodeValue();
            }
            // process @length
            if ((discriminatorResult = m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_LENGTH})) != null) {
                length = Integer.parseInt(discriminatorResult.getNodeValue());
            }
        }
        
        processDiscriminatorColumn(dmd, columnName, columnDefinition, length, discriminatorType);
    }

    /**
     * INTERNAL:
     * @param dmd
     */
    protected void processDiscriminatorValue(MetadataDescriptor dmd) {
        processDiscriminatorValue((XMLDescriptorMetadata)dmd, m_xmlHelper.locateNodeForEntity(dmd.getJavaClass()));
	}
	
    
    /**
     * INTERNAL:
	 * Process a discriminator value to set the class indicator on the root 
     * descriptor of the inheritance hierarchy. 
     * 
     * If there is no discriminator value, the class indicator defaults to 
     * the class name.
	 */
    private void processDiscriminatorValue(XMLDescriptorMetadata dmd, Node entityNode) {
	    String dValue = null;
	    Node result = m_xPathEngine.selectSingleNode(entityNode, new String[] {XMLConstants.DISCRIMINATOR_VALUE, XMLConstants.TEXT});
	    if (result != null && !result.getNodeValue().equals("")) {
	        dValue = result.getNodeValue();
	    }

	    processDiscriminatorValue(dmd, dValue);
	}
    
    /**
     * INTERNAL:
     * 
     * @param accessor
     * @param mapping
     */
    protected void processEnumerated(MetadataAccessor accessor, DirectToFieldMapping mapping) {
    	Node enumeratedNode = ((XMLAccessor) accessor).getEnumeratedNode();
        // handle enumerated
        boolean isOrdinal = true;   // default
        String enumeratedType = enumeratedNode.getNodeValue();
        if (enumeratedType != null && !enumeratedType.equals("")) {
        	isOrdinal = enumeratedType.equals(XMLConstants.ORDINAL);
        }
    	processEnumerated(accessor, isOrdinal, mapping);
    }
    
    /**
     * INTERNAL:
     * Process any entity definitions in the entity-mappings instance document.
     * 
     */
    private void processEntities() {
        NodeList nodes = m_xPathEngine.selectNodes(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.ENTITY});
        if (nodes != null) {
            // for each entity in the instance doc...
            for (int i=0; i<nodes.getLength(); i++) {
                processEntityNode(nodes.item(i));
            }
        }
    }
	
	/**
     * INTERNAL:
     * Process an entity, embeddable or mapped-superclass.
     * 
     * @param rootClass
     */
    protected void processEntityClass(Class cls) {
    	processEntityNode(m_xmlHelper.locateNode(cls));
    }
    
    /**
     * INTERNAL:
     * Process a given entity.
     * 
     * @param node the node in the DOM representing the entity being processed
     */
    private void processEntityNode(Node node) {
        // process @class (required)
    	String entityClassName = m_xmlHelper.getClassNameForNode(node);
    	Class entityClass = MetadataHelper.getClassForName(entityClassName, m_loader);

        // avoid double-processing of entities
        if (MetadataHelper.descriptorAlreadyExists(m_project, entityClass)) {
			return;
        }

        XMLDescriptorMetadata dmd = getMetadataDescriptor(entityClass);
        dmd.setIgnoreFlags();

        // process @name
        String alias = "";
        Node attr = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_NAME});
        if (attr != null) {
            alias = attr.getNodeValue();
        }
        
        processEntity(alias, dmd);

        // process @metadata-complete
		if (!dmd.shouldIgnoreAnnotations()) {
	        if ((attr = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_METADATA_COMPLETE})) != null) {
				dmd.setShouldIgnoreAnnotations(Boolean.parseBoolean(attr.getNodeValue()));
	        }			
		}
		
		// process persistence unit default access override
		// process @access
        if ((attr = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ATT_ACCESS})) != null) {
        	// use entity override value
        	m_access = attr.getNodeValue();
        }
        
        // apply the access, catalog, schema, and package defaults to the descriptor metadata
        dmd.setAccessType(m_access);
        dmd.setIsXmlPropertyAccess(m_access.equals(XMLConstants.PROPERTY));
        dmd.setCatalog(m_catalog);
        dmd.setSchema(m_schema);

        dmd.setAccessUsingMethods(m_access.equals(XMLConstants.PROPERTY));
        
        // process named-query
        processNamedQueries(node, new String[] {XMLConstants.NAMED_QUERY}, entityClassName);

        // process named-native-query
        processNamedNativeQueries(node, new String[] {XMLConstants.NAMED_NATIVE_QUERY}, entityClassName);
        
        // process sql-result-set-mappings
        processSQLResultSetMappings(node, new String[] {XMLConstants.SQL_RESULT_SET_MAPPING});

        Node result;
        // process table-generator
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.TABLE_GENERATOR})) != null) {
            preProcessTableGenerator(result);
        }

        // process sequence-generator
        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.SEQUENCE_GENERATOR})) != null) {
            preProcessSequenceGenerator(result);
        }

        // process table
        processTable(dmd, node);

        // process inheritance
        processInheritanceRoot(dmd, node);

        // process id-class (pkClass)
        processIdClass(dmd);
        
        // process association overrides
        processAssociationOverrides(dmd, node);
        
        // set our attribute overrides from the entity class before 
        // processing the accessors from the embeddable superclass
        processAttributeOverrides(dmd);

        // process mapped-superclass
        processMappedSuperclasses(dmd);

        // process attributes
        processAttributes(dmd, node);
        
        // If this descriptor has a composite primary key, check that all 
        // our composite primary key attributes were validated. 
        if (dmd.hasCompositePrimaryKey()) {
            if (dmd.pkClassWasNotValidated()) {
                throw ValidationException.invalidCompositePKSpecification(entityClass, dmd.getPKClassName());    
            }
        } else {
            // Descriptor has a single primary key. Validate an id 
            // attribute was found, unless we are an inheritance subclass.
            if (! dmd.hasPrimaryKeyFields() && !dmd.isInheritanceSubclass()) {
                throw ValidationException.noPrimaryKeyAnnotationsFound(entityClass);
            }
        }
        
        // process secondary-table(s)
        processSecondaryTables(dmd, node);

        // process listeners
        processEntityListeners(node, entityClassName, dmd);
    }

    /**
     * INTERNAL:
     * Parse the xml descriptor instance document represented by the provided URL.
     * The result will be a session containing a TopLink project with descriptors 
     * for any entities defined in the document, as well as any golbally defined
     * settings (set on the entity-mappings element).  Any existing project 
     * information (set from reading in project XML) and will not be overwritten.
     * 
     * @param session TopLink session containing a TopLink project to which persistence 
     * information (contained within the provided persistence ORM instance document) 
     * will be written
     * @param xmlDoumentURL the URL of the instance document to be processed
     * @param classLoader the class loader to be used
     * 
     */
    public Session processEntityMappings(AbstractSession session, URL xmlDocumentURL) {
        init(session, xmlDocumentURL);

        Node node;
        
        // process persistence unit default overrides
        // process catalog
        if ((node = m_xPathEngine.selectSingleNode(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.CATALOG, XMLConstants.TEXT})) != null) {
            m_catalog = node.getNodeValue();
        }
        // process schema
        if ((node = m_xPathEngine.selectSingleNode(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.SCHEMA, XMLConstants.TEXT})) != null) {
            m_schema = node.getNodeValue();
        }
        // process access
        if ((node = m_xPathEngine.selectSingleNode(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.ACCESS, XMLConstants.TEXT})) != null) {
            m_access = node.getNodeValue();
        }

        // process named-queries
        processNamedQueries(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.NAMED_QUERY});

        // process named-native-queries
        processNamedNativeQueries(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.NAMED_NATIVE_QUERY});

        // process sql-result-set-mappings
        processSQLResultSetMappings(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.SQL_RESULT_SET_MAPPING});
        
        // pre-process table-generators
        NodeList results = m_xPathEngine.selectNodes(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.TABLE_GENERATOR});
        if (results != null) {
            for (int i=0; i<results.getLength(); i++) {
                preProcessTableGenerator(results.item(i));
            }
        }

        // pre-process sequence-generators
        results = m_xPathEngine.selectNodes(m_document, new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.SEQUENCE_GENERATOR});
        if (results != null) {
            for (int i=0; i<results.getLength(); i++) {
                preProcessSequenceGenerator(results.item(i));
            }
        }

        // process entities
        processEntities();
        
        // handle sequencing
        m_sequencingProcessor.process(session.getProject().getLogin());

        for (Iterator dmdIt = m_relatedEntities.iterator(); dmdIt.hasNext();) {
            processRelatedEntity((XMLDescriptorMetadata) dmdIt.next());
        }
        
        return session;
    }

    
    /**
     * INTERNAL:
     * Process the related entities. That is, mappings and inheritance etc.
     */
    protected void processRelatedEntity(XMLDescriptorMetadata dmd) {
        // process an inheritance subclass specifics
        if (dmd.isInheritanceSubclass()) {
            processInheritanceSubclass(dmd);
        }
            
        // process the relationship accessors
        for (Iterator dmdIt = dmd.getRelationshipAccessors().iterator(); dmdIt.hasNext();) {
        	XMLAccessor accessor = (XMLAccessor) dmdIt.next();
            processRelationshipAccessor(accessor);  
        }
    }
    
    /**
     * INTERNAL:
     * Process all the event tags for the listener class - the names of the callback
     * methods will be stored in the listener for initialization later on.
     *     
     * @param cbListener 
     * @param node 
     */
    protected void processEvents(XMLCBListener cbListener, Node node) {
        // process pre-persist
        addEventMethodNameToListener(cbListener, node, XMLConstants.PRE_PERSIST);
        // process post-persist
        addEventMethodNameToListener(cbListener, node, XMLConstants.POST_PERSIST);
        // process pre-remove
        addEventMethodNameToListener(cbListener, node, XMLConstants.PRE_REMOVE);
        // process post-remove
        addEventMethodNameToListener(cbListener, node, XMLConstants.POST_REMOVE);
        // process pre-update
        addEventMethodNameToListener(cbListener, node, XMLConstants.PRE_UPDATE);
        // process post-update
        addEventMethodNameToListener(cbListener, node, XMLConstants.POST_UPDATE);
        // process post-load
        addEventMethodNameToListener(cbListener, node, XMLConstants.POST_LOAD);
    }
    
    /**
     * INTERNAL:
     * Process all the event tags for the listener class - the names of the callback
     * methods will be stored in the map for initialization later on.
     *     
     * @param methodMap
     * @param node 
     */
    protected void processEventMethodNames(HashMap methodMap, Node node) {
        // process pre-persist
        addEventMethodNameToMap(methodMap, node, XMLConstants.PRE_PERSIST);
        // process post-persist
        addEventMethodNameToMap(methodMap, node, XMLConstants.POST_PERSIST);
        // process pre-remove
        addEventMethodNameToMap(methodMap, node, XMLConstants.PRE_REMOVE);
        // process post-remove
        addEventMethodNameToMap(methodMap, node, XMLConstants.POST_REMOVE);
        // process pre-update
        addEventMethodNameToMap(methodMap, node, XMLConstants.PRE_UPDATE);
        // process post-update
        addEventMethodNameToMap(methodMap, node, XMLConstants.POST_UPDATE);
        // process post-load
        addEventMethodNameToMap(methodMap, node, XMLConstants.POST_LOAD);
    }
    
    /**
     * INTERNAL:
     * Process an id element if there is one.
     */
    protected void processId(MetadataAccessor metadataAccessor, DatabaseField field) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
        if (accessor.isId()) {
            processId(accessor, field, accessor.getGeneratedValueNode());
        }
    }

    /**
     * INTERNAL:
     * Process an id-class. It is used to specify a composite primary key class. 
     * The primary keys will be processed and stored from the PK class so that 
     * they may be validated against the fields or properties of the entity bean.
     * The access type of a primary key class is determined by the access 
     * type of the entity for which it is the primary key.
     * 
     * @param dmd XMLDescriptorMetadata object for the associated entity
     */
    protected void processIdClass(XMLDescriptorMetadata dmd) {
        Class cls = dmd.getJavaClass();
        Node node = m_xmlHelper.locateNode(cls);
        
        Node result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.ID_CLASS});
        if (result != null) {
            // process @class (required)
            processIdClass(dmd, m_xmlHelper.getClassForNode(result));
        }
    }

    /**
     * INTERNAL:
     * Process inheritance.  Inheritance must be specified on the 
     * entity class that is the root of then entity class hierarchy.
     */
    protected void processInheritanceRoot(XMLDescriptorMetadata dmd, Node entityNode) {
        if (dmd.ignoreInheritanceAnnotations()) {
            // Project XML/XML merging. Project XML wins
            getLogger().logWarningMessage(MetadataLogger.IGNORE_INHERITANCE, dmd);
        } else {
            Node inheritanceNode = m_xPathEngine.selectSingleNode(entityNode, new String[] {XMLConstants.INHERITANCE});
            if (inheritanceNode != null) {
            	String strategy = XMLConstants.SINGLE_TABLE;
            	
                // process @strategy
                Node rootResult = m_xPathEngine.selectSingleNode(inheritanceNode, new String[] {XMLConstants.ATT_STRATEGY});
                if (rootResult != null) {
                    strategy = rootResult.getNodeValue();
                }
	
	            // store the strategy on the descriptor metadata
	            dmd.setInheritanceStrategy(strategy);
	            
	            // process discriminator-column
	            processDiscriminatorColumn(dmd, entityNode);
	            
	            // process discriminator-value
	            processDiscriminatorValue(dmd, entityNode);
            }
        }
    }

    /**
     * INTERNAL:
     * Process a join-column and return a populated JoinColumnDetails.
     * 
     * @param joinColumnNode
     * @param attributeName
     * @param targetTableName
     * @param dmd
     * @param referenceDmd
     * @return
     */
    private MetadataJoinColumn processJoinColumn(Node joinColumnNode, XMLAccessor accessor, String targetTable, MetadataDescriptor sourceDmd) {
        // set defaults
        String name = "";
        String referencedColumnName = "";
        boolean isUnique = false;
        boolean isNullable = true;
        boolean isInsertable = true;
        boolean isUpdatable = true;
        String columnDefinition = "";
        String tableName = "";
        Node result;
        
        // process @name - a.k.a. fkColumn
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_NAME})) != null) {
            name = result.getNodeValue();
        }
        // process @referenced-column-name - a.k.a. pkColumn
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_REFERENCED_COLUMN_NAME})) != null) {
            referencedColumnName = result.getNodeValue();
        }
        // process @unique
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_UNIQUE})) != null) {
            isUnique = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @nullable
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_NULLABLE})) != null) {
            isNullable = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @insertable
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_INSERTABLE})) != null) {
            isInsertable = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @updatable
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_UPDATABLE})) != null) {
            isUpdatable = Boolean.parseBoolean(result.getNodeValue());
        }
        // process @column-definition
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_COLUMN_DEFINITION})) != null) {
            columnDefinition = result.getNodeValue();
        }
        // process @table - will be attached to fkColumn
        if ((result = m_xPathEngine.selectSingleNode(joinColumnNode, new String[] {XMLConstants.ATT_SECONDARY_TABLE})) != null) {
            tableName = result.getNodeValue();
        }
        
        return processJoinColumn(
    			accessor,
        		targetTable, 
        		sourceDmd, 
        		name, 
        		referencedColumnName, 
        		columnDefinition, 
        		tableName, 
        		isUnique, 
        		isNullable, 
        		isInsertable, 
        		isUpdatable);
    }

    /**
     * INTERNAL:
     * Process any join-columns and return a list of JoinColumnDetails.
     * 
     * @param dmd
     * @param referenceDmd
     * @param node
     * @param xPath
     * @return
     */
    protected ArrayList processJoinColumns(MetadataAccessor metadataAccessor) {
        ArrayList allJoinColumns = new ArrayList();
        XMLAccessor accessor = (XMLAccessor) metadataAccessor; 
        
        XMLDescriptorMetadata dmd = accessor.getMetadataDescriptor();
        String targetTableName = dmd.getPrimaryTableName();
        MetadataDescriptor referenceDmd = accessor.getReferenceMetadataDescriptor();
        String sourceTableName = referenceDmd.getPrimaryTableName();
        
        Node node = accessor.getAttributeNode();
        String attributeName = accessor.getAttributeName();
        
        // process join-column(s)
        NodeList joinColumns;
        if (dmd.hasAssociationOverrideFor(accessor)) {
        	joinColumns = (NodeList)(dmd.getAssociationOverrideFor(accessor)[0]);
        } else {
            joinColumns = m_xPathEngine.selectNodes(node, new String[] {XMLConstants.JOIN_COLUMN});
        }
        
        if (referenceDmd.hasCompositePrimaryKey()) {
            // composite primary key: the number of <join-column> elements 
        	// specified should equal the number of primary key fields
            if (joinColumns == null || joinColumns.getLength() != referenceDmd.getPrimaryKeyFields().size()) {
            	// TODO: create a non-annotation specific message to throw here
                throw ValidationException.incompleteJoinColumnsSpecified(attributeName, dmd.getJavaClass());
            }
            for (int i=0; i<joinColumns.getLength(); i++) {
                allJoinColumns.add(processJoinColumn(joinColumns.item(i), accessor, targetTableName, referenceDmd));
            }
        } else {
            // single primary key
            if (joinColumns != null && joinColumns.getLength()!=0) {
            	if (joinColumns.getLength()>1) {
                	// TODO: create a non-annotation specific message to throw here
                    throw ValidationException.excessiveJoinColumnsSpecified(attributeName, dmd.getJavaClass());
            	}
                allJoinColumns.add(processJoinColumn(joinColumns.item(0), accessor, targetTableName, referenceDmd));
            } else {
                addJoinColumnDefault(allJoinColumns, sourceTableName, targetTableName, dmd);
            }
        }
            
        return allJoinColumns;
    }

    /**
     * INTERNAL:
     * Process join-table information.
     * 
     * @param dmd 
     * @param attributeNode 
     * @param mapping
     * @return 
     */
    protected void processJoinTable(MetadataAccessor metadataAccessor, ManyToManyMapping mapping) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	
        DatabaseTable relationTable = getRelationTable(accessor);
        mapping.setRelationTable(relationTable);
        String relationTableName = relationTable.getQualifiedName();

        // process join-column and inverse-join-column
        ArrayList sourceKeys = new ArrayList();
        ArrayList targetKeys = new ArrayList();
        
        Node joinTableNode = accessor.getJoinTableNode();
        if (joinTableNode != null) {
	        // process join-columns
	        NodeList jCols = m_xPathEngine.selectNodes(joinTableNode, new String[] {XMLConstants.JOIN_COLUMN});
	        if (jCols != null) {
	        	for (int i=0; i<jCols.getLength(); i++) {
	                sourceKeys.add(processJoinColumn(jCols.item(i), accessor, relationTableName, accessor.getMetadataDescriptor()));
	        	}
	        }            	
	
	        // process inverse-join-column
	        jCols = m_xPathEngine.selectNodes(joinTableNode, new String[] {XMLConstants.INVERSE_JOIN_COLUMN});
	        if (jCols != null) {
	        	for (int i=0; i<jCols.getLength(); i++) {
	                targetKeys.add(processJoinColumn(jCols.item(i), accessor, relationTableName, accessor.getReferenceMetadataDescriptor()));
	        	}
	        }            	
        }
        
        processJoinTable(accessor, mapping, sourceKeys, targetKeys);
    }    

    /**
     * INTERNAL:
     * Process entity listeners.  An XMLCBListener will be created for each listener.
     * 
     * @param node
     * @param entityClassName 
     * @param dmd 
     */
    private void processEntityListeners(Node node, String entityClassName, XMLDescriptorMetadata dmd) {
    	HashMap listenerMap = new HashMap();

        // For listeners you need not set the actual values, since the
        // annotations processor will do it based on the flag this processor
        // sets and what the anotations processor finds in annotations 
        // (taking meta-data complete into consideration as well)
        
		// process exclude-superclass-listeners
        dmd.setXmlExcludeSuperclassListeners(m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.EXCLUDE_SUPERCLASS_LISTENERS}) != null);
        
    	// process exclude-default-listeners
        dmd.setXmlExcludeDefaultListeners(m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.EXCLUDE_DEFAULT_LISTENERS}) != null);
    	
    	// handle default listeners
        // You shouldn't have to make this call either.
    	//listenerMap.put(XMLConstants.DEFAULT_ENTITY_LISTENERS, dmd.getDefaultListeners());

    	// handle entity-defined listeners
    	ArrayList entityListenerList = new ArrayList(); 
        createCBListeners(node, new String[] {XMLConstants.ENTITY_LISTENERS, XMLConstants.ENTITY_LISTENER}, entityClassName, entityListenerList);
        listenerMap.put(XMLConstants.ENTITY_LISTENERS, entityListenerList);
        
        // process callback methods on the entity itself
        ArrayList entityCallbacks = new ArrayList();
        if (m_xmlHelper.entityHasCallbackMethod(node)) {
            XMLEntityCBListener entityCBListener = new XMLEntityCBListener(entityClassName);
            processEvents(entityCBListener, node);
            entityCallbacks.add(entityCBListener);
        }
        listenerMap.put(XMLConstants.CALLBACK_METHODS, entityCallbacks);

        // add the map of listeners keyed on class name 
        // for processing during the deploy stage 
        m_entityListeners.put(entityClassName, listenerMap);
    }

    /**
     * INTERNAL:
     * Process a M-M into a TopLink ManyToMany mapping.
     */
    protected void processManyToMany(MetadataAccessor metadataAccessor) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
        processManyToMany(
        		accessor, 
        		accessor.getMappedBy(), 
        		getCascadeTypes(accessor), 
        		accessor.getFetchType().equals(XMLConstants.LAZY), 
        		accessor.getTargetEntity());
    }
    
    /**
     * INTERNAL:
     * Process a M-1 into a TopLink OneToOne mapping.
     * 
     * Note: Target foreign keys are not valid for m-1 mapping
     */
    protected void processManyToOne(MetadataAccessor metadataAccessor) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	processManyToOne(
        		accessor, 
        		getCascadeTypes(accessor),
        		accessor.getFetchType().equals(XMLConstants.LAZY),
        		accessor.isOptional(),
        		accessor.getTargetEntity());
    }

    /**
     * INTERNAL:
     * Process map-key for a one-to-many or many-to-many mapping. 
     * 
     * @param accessor
     * @param mapping
     * @return the map key method name that should be used, null otherwise
     */
	protected String processMapKey(MetadataAccessor metadataAccessor, CollectionMapping mapping) {
		XMLAccessor accessor = (XMLAccessor) metadataAccessor;
        if (!accessor.hasMapKey()) {
        	return null;
		}
        return processMapKey(accessor, mapping, accessor.getMapKey());
    }

    
    /**
     * INTERNAL:
     * Process any mapped-superclasses if there are any. There may be
     * several mapped-superclasses for any given Entity.
     */
    protected void processMappedSuperclasses(XMLDescriptorMetadata dmd) {
        for (Iterator superclassIt = dmd.getMappedSuperclasses().iterator(); superclassIt.hasNext(); ) {
        	Class cls = (Class) superclassIt.next();
            // Process the accessors from the mapped superclass.
            processAccessors(cls, dmd);
            
            // Process the attribute overrides on this MappedSuperclass, if
            // there are any before processing its parent MappedSuperclass.
            processAttributeOverrides(cls, dmd);
        }
    }
    
    /**
     * INTERNAL:
     * 
     * @param node 
     * @param xPath 
     */
    private void processNamedNativeQueries(Node node, String[] xPath) {
        processNamedNativeQueries(node, xPath, "");
    }
    
    /**
     * INTERNAL:
     * Process named-queries at either the entity-mappings or entity level.  The
     * queries will be stored in a hashmap - EntityManagerSetupImpl will call 
     * 'addNamedQueriesToSession()' after processing; this is when the queries
     * will be added to the session.
     * 
     * @param node either entity-mapping or entity node
     * @param xpath to search for named-native-query tag(s)
     * be null if processing at an entity-mapping level
     * @param entityClass the owning class - for warning messages
     */
    private void processNamedNativeQueries(Node node, String[] xPath, String entityClass) {
        NodeList queries = m_xPathEngine.selectNodes(node, xPath);
        if (queries != null) {
            // for each named native query...
            for (int i=0; i<queries.getLength(); i++) {
                Node queryNode = queries.item(i);
                
                // process @name (required)
                String queryName = m_xPathEngine.selectSingleNode(queryNode, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
                
                // make sure the query doesn't already exist in the map
                if (m_namedNativeQueries.containsKey(queryName)) {
                    getLogger().logWarningMessage(MetadataLogger.IGNORE_QUERY, queryName);
                    continue;
                }

                // process query
                Node ejbqlNode = m_xPathEngine.selectSingleNode(queryNode, new String[] {XMLConstants.QUERY, XMLConstants.TEXT}); 
                String ejbql = "";
                if (ejbqlNode != null && ejbqlNode.getNodeValue() != null) {
                	ejbql = ejbqlNode.getNodeValue();
                }

                // create properties for this query
                HashMap props = new HashMap();
                // store the query string
                props.put(XMLConstants.QUERY, ejbql);
                
                // process @result-class
                Node result = m_xPathEngine.selectSingleNode(queryNode, new String[] {XMLConstants.ATT_RESULT_CLASS});
                if (result != null && !result.getNodeValue().equals("")) {
                    props.put(XMLConstants.ATT_RESULT_CLASS, m_xmlHelper.getFullyQualifiedClassName(result.getNodeValue()));
                }
                
                // process @result-set-mapping
                result = m_xPathEngine.selectSingleNode(queryNode, new String[] {XMLConstants.ATT_RESULT_SET_MAPPING});
                if (result != null && !result.getNodeValue().equals("")) {
                    props.put(XMLConstants.ATT_RESULT_SET_MAPPING, result.getNodeValue());
                }

                // process hints
            	props.put(XMLConstants.QUERY_HINT, processQueryHints(queryNode, queryName, entityClass));
                
                // store the query info for later processing
                m_namedNativeQueries.put(queryName, props);
            }
        }
    }

    /**
     * INTERNAL:
     * 
     * @param node 
     * @param xPath 
     */
    private void processNamedQueries(Node node, String[] xPath) {
        processNamedQueries(node, xPath, "");
    }
    
    /**
     * INTERNAL:
     * Process named queries at either the entity-mapping or entity level.  The 
     * queries will be stored in a hashmap - EntityManagerSetupImpl will call 
     * 'addNamedQueriesToSession()' after processing; this is when the queries
     * will be added to the session.
     * 
     * @param node either entity-mapping or entity node
     * @param xpath to search for named-native-query tag(s)
     * be null if processing at an entity-mapping level
     * @param entityClass the owning class - for warning messages
     */
    private void processNamedQueries(Node node, String[] xPath, String entityClass) {
        NodeList queries = m_xPathEngine.selectNodes(node, xPath);
        if (queries != null) {
            // for each named query...
            for (int i=0; i<queries.getLength(); i++) {
                Node queryNode = queries.item(i);

                // process @name (required)
                String queryName = m_xPathEngine.selectSingleNode(queryNode, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
                
                // make sure the query doesn't already exist in the map
                if (m_namedQueries.containsKey(queryName)) {
                    getLogger().logWarningMessage(MetadataLogger.IGNORE_QUERY, queryName, entityClass);
                    continue;
                }

                // process query
                Node ejbqlNode = m_xPathEngine.selectSingleNode(queryNode, new String[] {XMLConstants.QUERY, XMLConstants.TEXT}); 
                String ejbql = "";
                if (ejbqlNode != null && ejbqlNode.getNodeValue() != null) {
                	ejbql = ejbqlNode.getNodeValue();
                }

                // create properties for this query
                HashMap props = new HashMap();
                // store the query string
                props.put(XMLConstants.QUERY, ejbql);

                // process hints
            	props.put(XMLConstants.QUERY_HINT, processQueryHints(queryNode, queryName, entityClass));

                // store the query info for later processing
                m_namedQueries.put(queryName, props);
            }
        }
    }
    
    /**
     * INTERNAL:
     * Process a one-to-many into a TopLink OneToMany mapping. If 
     * a join-table is found however, we must create a ManyToMany 
     * mapping.
     */
    protected void processOneToMany(MetadataAccessor metadataAccessor) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	processOneToMany(accessor, accessor.getAttributeNode(), accessor.getMappedBy());
    }
	
    /**
     * INTERNAL:
     * Process a one-to-one into a TopLink OneToOne mapping.
     */
    protected void processOneToOne(MetadataAccessor metadataAccessor) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	String mappedBy = "";
        Class targetEntity = void.class;
        Object[] cascade = {};
        boolean optional = true; 
        boolean usesIndirection = false;
        
        if (accessor.isOneToOne()) {
            targetEntity = accessor.getTargetEntity();
            cascade = getCascadeTypes(accessor);
            usesIndirection = accessor.getFetchType().equals(XMLConstants.LAZY);
            optional = accessor.isOptional();
            mappedBy = accessor.getMappedBy();
        }
	
        processOneToOne(accessor, mappedBy, targetEntity, cascade, optional, usesIndirection);
    }
    
    /**
     * INTERNAL:
     * Process an order-by for collection mappings.
     * 
     * @param attributeNode
     * @param mapping
     */
    protected void processOrderBy(MetadataAccessor metadataAccessor, CollectionMapping mapping) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor; 
    	if (accessor.hasOrderBy()) {
    		processOrderBy(accessor, mapping, accessor.getOrderByNode().getNodeValue());
    	}
    }
    
    /**
     * INTERNAL:
     * @param key
     * @param contextNode
     */
    protected void processPersistenceUnitDefault(String key, Node contextNode, HashMap puDefaults) {
        String nodeValue;
        Object existingValue;
        Node node;
        
        if ((node = m_xPathEngine.selectSingleNode(contextNode, new String[] {key, XMLConstants.TEXT})) != null) {
        	nodeValue = node.getNodeValue();
        	existingValue = puDefaults.get(key);
        	// check for conflict
        	if (existingValue != null && (!((String)existingValue).equals(nodeValue))) {
        		throw ValidationException.persistenceUnitMetadataConflict(key);
        	}
        	puDefaults.put(key, nodeValue);
        }
    }
    
    /**
     * INTERNAL:
     * Process persistence unit metadata and defaults, and apply them to each entity in the collection.  Any
     * conflicts in elements defined in multiple documents will cause an exception to be thrown.  
     * 
     * @param mappingFiles
     * @param entities
     * @return
     */
    public void processPersistenceUnitMetadata(AbstractSession session, Collection mappingFiles, Collection entities) {
    	m_xPathEngine = XPathEngine.getInstance();
    	m_session = session;
    	
    	// set defaults
    	m_defaultAccess = XMLConstants.FIELD;
    	m_defaultCatalog = "";
    	m_defaultSchema = "";
    	
    	HashMap defaultListenerList = new HashMap();
        HashMap puDefaults = new HashMap();
    	puDefaults.put(XMLConstants.ENTITY_LISTENERS, defaultListenerList);

    	// for each orm xml instance document, process persistence unit metadata/defaults
    	for (Iterator mapIt = mappingFiles.iterator(); mapIt.hasNext(); ) {
            try {
                // initialize a helper for navigating the instance document 
            	m_xmlHelper = new XMLHelper(m_loader.getResource((String) mapIt.next()), m_loader);
                
                // create a context node referencing persistence-unit-metadata
                String[] xPath = new String[] {XMLConstants.ENTITY_MAPPINGS, XMLConstants.PU_METADATA};
                Node contextNode = m_xPathEngine.selectSingleNode(m_xmlHelper.getDocument(), xPath);
                if (contextNode == null) {
                	continue;
                }

                // process xml-mapping-metadata-complete
        		Node result = m_xPathEngine.selectSingleNode(contextNode, new String[] {XMLConstants.METADATA_COMPLETE});
        		if (result != null) {
        			puDefaults.put(XMLConstants.METADATA_COMPLETE, true);
        		} else {
        			// if there isn't a xml-mapping-metadata-complete element, but there was in a 
        			// document processed previously, we need to throw a conflict exception
        			if (puDefaults.get(XMLConstants.METADATA_COMPLETE) != null) {
        				throw ValidationException.persistenceUnitMetadataConflict(XMLConstants.METADATA_COMPLETE);
        			}
        		}

        		// process persistence unit defaults
                contextNode = m_xPathEngine.selectSingleNode(contextNode, new String[] {XMLConstants.PU_DEFAULTS});
                if (contextNode == null) {
                	continue;
                }

                // process schema
                processPersistenceUnitDefault(XMLConstants.SCHEMA, contextNode, puDefaults);
                // process catalog
                processPersistenceUnitDefault(XMLConstants.CATALOG, contextNode, puDefaults);
                // process access
                processPersistenceUnitDefault(XMLConstants.ACCESS, contextNode, puDefaults);

                // process cascade-persist
                result = m_xPathEngine.selectSingleNode(contextNode, new String[] {XMLConstants.CASCADE_PERSIST});
                if (result != null) {
                    puDefaults.put(XMLConstants.CASCADE_PERSIST, true);
                } else {
        			// if there isn't a cascade-persist element, but there was in a document 
                	// processed previously, we need to throw a conflict exception
	                if (puDefaults.get(XMLConstants.CASCADE_PERSIST) != null) {
	                	throw ValidationException.persistenceUnitMetadataConflict(XMLConstants.CASCADE_PERSIST);
	                }
                }
                
                // process default entity-listeners
                // no conflict checking will be done here - any/all default listeners will be added to the list
                xPath = new String[] {XMLConstants.ENTITY_LISTENERS, XMLConstants.ENTITY_LISTENER};
                NodeList listenerNodes = m_xPathEngine.selectNodes(contextNode, xPath);
                if (listenerNodes != null && listenerNodes.getLength() > 0) {
                	for (int i=0; i<listenerNodes.getLength(); i++) {
                		Node listenerNode = listenerNodes.item(i);
                        String listenerClassName = m_xmlHelper.getClassNameForNode(listenerNode);
                        HashMap methodMap = new HashMap();
                        processEventMethodNames(methodMap, listenerNode);
                        defaultListenerList.put(listenerClassName, methodMap);
                	}
                }
            } catch (RuntimeException re) {
            	throw re;
            }
    	}
    	
		String access = (String) puDefaults.get(XMLConstants.ACCESS);		
		String catalog = (String) puDefaults.get(XMLConstants.CATALOG);
		String schema =  (String) puDefaults.get(XMLConstants.SCHEMA);
		
		// set the default access if non-null
		if (access != null) {
			m_defaultAccess = access;
		}
		// set the default schema if non-null
		if (schema != null) {
			m_defaultSchema = schema;
		}
		// set the default catalog if non-null
		if (catalog != null) {
			m_defaultCatalog = catalog;
		}
		
    	// apply persistence unit metadata/defaults to each entity in the collection
    	for (Iterator entityIt = entities.iterator(); entityIt.hasNext(); ) {
    		Class entityClass = (Class)entityIt.next();
    		XMLDescriptorMetadata mdd = new XMLDescriptorMetadata(entityClass, null);
            getDescriptorMetadataMap().put(entityClass, mdd);
    		
    		mdd.setAccessType(m_defaultAccess);
    		mdd.setCatalog(m_defaultSchema);
    		mdd.setSchema(m_defaultCatalog);

    		if (puDefaults.get(XMLConstants.CASCADE_PERSIST) != null) {
    			mdd.setShouldUseCascadePersist();
    		}

    		// apply default listeners
    		Iterator keys = defaultListenerList.keySet().iterator();
    		while (keys.hasNext()) {
    			String listenerClassName = (String) keys.next();
    			createDefaultCBListener(listenerClassName, entityClass.getName(), (HashMap) defaultListenerList.get(listenerClassName), (ArrayList) mdd.getDefaultListeners());
			}
    		
			// indicate whether to ignore annotations or not 
			mdd.setShouldIgnoreAnnotations(puDefaults.get(XMLConstants.METADATA_COMPLETE) != null);
    	}
    }
    
    /**
     * INTERNAL:
     * @param pkJoinColNode
     * @param sourceTable
     * @param targetTable
     * @param dmd
     * @return
     */
    protected MetadataJoinColumn processPrimaryKeyJoinColumnNode(Node pkJoinColNode, String sourceTable, String targetTable, MetadataDescriptor dmd) {
        Node result;
        String name = "";
        String referencedColumnName = "";
        String columnDefinition = "";
        
        // process @name
        if ((result = m_xPathEngine.selectSingleNode(pkJoinColNode, new String[] {XMLConstants.ATT_NAME})) != null) {
            name = result.getNodeValue();
        }
        // process @referenced-column-name
        if ((result = m_xPathEngine.selectSingleNode(pkJoinColNode, new String[] {XMLConstants.ATT_REFERENCED_COLUMN_NAME})) != null) {
            referencedColumnName = result.getNodeValue();
        }
        // process @column-details
        if ((result = m_xPathEngine.selectSingleNode(pkJoinColNode, new String[] {XMLConstants.ATT_COLUMN_DEFINITION})) != null) {
            columnDefinition = result.getNodeValue();
        }
        return processPrimaryKeyJoinColumn(name, referencedColumnName, columnDefinition, sourceTable, targetTable, dmd);    
    }
    
    /**
     * INTERNAL:
     * @param pkJoinCols
     * @param sourceTableName
     * @param targetTableName
     * @param dmd
     */
    protected ArrayList processPrimaryKeyJoinColumns(Object[] pkJoinCols, String sourceTableName, String targetTableName, MetadataDescriptor dmd) {
    	ArrayList joinColumnDetails = new ArrayList();
	    for (int i=0; i<pkJoinCols.length; i++) {
	    	joinColumnDetails.add(processPrimaryKeyJoinColumnNode((Node) pkJoinCols[i], sourceTableName, targetTableName, dmd));
	    }
	    return joinColumnDetails;
    }

    /**
     * INTERNAL:
	 * Process the primary key join columns for a given entity.
     * 
     * @param sourceTable 
     * @param targetTable 
     * @param element will be either a Node or Class depending on where this method is called from
     * @param dmd
     * @return ArrayList containing 0 or more JoinColumnDetails
     */
    protected ArrayList processPrimaryKeyJoinColumns(String sourceTable, String targetTable, Object element, MetadataDescriptor dmd) {
        Node entityNode = m_xmlHelper.locateNode(dmd.getJavaClass());
    	Node node;
    	if (element instanceof String) {
    		node = m_xmlHelper.locateNodeForAttribute(entityNode, (String) element);
    	} else {
    		node = entityNode;
    	}

    	ArrayList joinColumnDetails = new ArrayList();
		Class entityClass = dmd.getJavaClass();
		
        // look for primary-key-join-column(s) elements
        NodeList primaryKeyJoinColumns = m_xPathEngine.selectNodes(node, new String[] {XMLConstants.PK_JOIN_COLUMN});
        
        // validation
        if (dmd.hasCompositePrimaryKey()) {
            // the number of primary-key-join-column entries should equal the number of primary key fields
            if (primaryKeyJoinColumns == null || primaryKeyJoinColumns.getLength() != dmd.getPrimaryKeyFields().size()) {
                throw ValidationException.incompletePrimaryKeyJoinColumnsSpecified(entityClass);
            }
        } else {
            if (primaryKeyJoinColumns != null && primaryKeyJoinColumns.getLength() > 1) {
                throw ValidationException.excessivePrimaryKeyJoinColumnsSpecified(entityClass);
            }
        }

        // process primary-key-join-column(s)
        if (primaryKeyJoinColumns != null) {
            for (int i=0; i<primaryKeyJoinColumns.getLength(); i++) {
                Node pkJoinColumnNode = primaryKeyJoinColumns.item(i);
                Node result;
                String name = "";
                String referencedColumnName = "";
                String columnDefinition = "";
                
                // process @name
                if ((result = m_xPathEngine.selectSingleNode(pkJoinColumnNode, new String[] {XMLConstants.ATT_NAME})) != null) {
                    name = result.getNodeValue();
                }
                // process @referenced-column-name
                if ((result = m_xPathEngine.selectSingleNode(pkJoinColumnNode, new String[] {XMLConstants.ATT_REFERENCED_COLUMN_NAME})) != null) {
                    referencedColumnName = result.getNodeValue();
                }
                // process @column-details
                if ((result = m_xPathEngine.selectSingleNode(pkJoinColumnNode, new String[] {XMLConstants.ATT_COLUMN_DEFINITION})) != null) {
                    columnDefinition = result.getNodeValue();
                }

                joinColumnDetails.add(processPrimaryKeyJoinColumn(name, referencedColumnName, columnDefinition, sourceTable, targetTable, dmd));
            }
		}

        // add defaults if necessary
		addJoinColumnDefault(joinColumnDetails, sourceTable, targetTable, dmd);
		
		return joinColumnDetails;
	}
	
	/**
	 * INTERNAL:
	 * Process any query-hints for a given node and store them in a map.
	 * 
	 * @param queryNode
	 * @param queryName
	 * @param entityClass
	 * @return HashMap of query-hints for a given node, or an empty HashMap if none exist.
	 */
	private HashMap processQueryHints(Node queryNode, String queryName, String entityClass) {
		HashMap hintMap = new HashMap();
		NodeList hints = m_xPathEngine.selectNodes(queryNode, new String[] {XMLConstants.QUERY_HINT});
	    if (hints != null) {
	        // for each query hint...
	        for (int h=0; h<hints.getLength(); h++) {
	            Node hintNode = hints.item(h);
	            // process @name (required)
	            String hintName = m_xPathEngine.selectSingleNode(hintNode, new String[] {XMLConstants.ATT_NAME}).getNodeValue();
	            // process @value (required)
	            String hintValue = m_xPathEngine.selectSingleNode(hintNode, new String[] {XMLConstants.ATT_VALUE}).getNodeValue();
	            // determine the type of the hint
	            Object typedHintValue = getTypedHintValue(hintName, hintValue, queryName, entityClass);
	            if (typedHintValue != null) {
	                // store the hint name/value
	            	hintMap.put(hintName, typedHintValue);
	            }
	        }
	    }
	    return hintMap;
    }
    
    /**
     * INTERNAL:
     * Process secondary-table(s) for a given entity.  Assumed here is that the 
     * entity class has been processed for a primary table and primary key.
     * 
     * @param dmd 
     * @param entityNode 
     */
    private void processSecondaryTables(XMLDescriptorMetadata dmd, Node entityNode) {
        NodeList secondaryTables = m_xPathEngine.selectNodes(entityNode, new String[] {XMLConstants.SECONDARY_TABLE});
        if (secondaryTables != null) {
            for (int i=0; i<secondaryTables.getLength(); i++) {
                Node tableNode = secondaryTables.item(i);

                // set defaults
                String catalog = m_catalog;
                String schema = m_schema;

                // process @name (required)
                Node result = m_xPathEngine.selectSingleNode(tableNode, new String[] {XMLConstants.ATT_NAME});
                String tableName = result.getNodeValue();
                
                // process @catalog
                if ((result = m_xPathEngine.selectSingleNode(tableNode, new String[] {XMLConstants.ATT_CATALOG})) != null) {
                    catalog = result.getNodeValue();
                }
                // process @schema
                if ((result = m_xPathEngine.selectSingleNode(tableNode, new String[] {XMLConstants.ATT_SCHEMA})) != null) {
                    schema = result.getNodeValue();
                }
                
                processSecondaryTable(
                		tableName, 
                		schema, 
                		catalog, 
                		getUniqueConstraints(tableNode), 
                		getPrimaryKeyJoinColumns(tableNode),
                		dmd);
            }
        }
    }
	
    /**
     * INTERNAL:
     * Process sql-result-set-mappings and store them on the session.
     * 
     * @param node
     * @param xPath
     */
    protected void processSQLResultSetMappings(Node node, String[] xPath) {
        NodeList sqlResultSetNodes = m_xPathEngine.selectNodes(node, xPath);
        if (sqlResultSetNodes != null) {
            for (int i=0; i<sqlResultSetNodes.getLength();i++) {
                m_session.getProject().addSQLResultSetMapping(createSQLResultSetMapping(sqlResultSetNodes.item(i))); 
            }
        }
    }
    
    /**
     * INTERNAL:
     * Process table information.
     * 
     * @param dmd the XMLDescriptorMetadata object of the tables's owning entity
     * @param node the DOM node representing the entity that owns the table
     */
    private void processTable(XMLDescriptorMetadata dmd, Node node) {
    	// project xml/entity-mappings xml merging:  project xml wins
        if (dmd.ignoreTableAnnotations()) {
            getLogger().logWarningMessage(MetadataLogger.IGNORE_TABLE, dmd.getJavaClass());
        } else {
	        // process table
	        Node result;
	        if ((result = m_xPathEngine.selectSingleNode(node, new String[] {XMLConstants.TABLE})) != null) {
		        // set default/global values
		        String schemaName = m_schema;
		        String catalogName = m_catalog;
		        String tableName = "";
	            Node attr;
	            
	            // process @name
	            if ((attr = m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_NAME})) != null) {
	                tableName = attr.getNodeValue();
	            }
	            // process @schema
	            if ((attr = m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_SCHEMA})) != null) {
	                schemaName = attr.getNodeValue();
	            }
	            // process @catalog
	            if ((attr = m_xPathEngine.selectSingleNode(result, new String[] {XMLConstants.ATT_CATALOG})) != null) {
	                catalogName = attr.getNodeValue();
	            }

	        	// create the table and add set it as primary
	            processTable(tableName, catalogName, schemaName, getUniqueConstraints(result), dmd);
	        } else {
	            processDefaultTable(dmd);
	        }
        }
    }

    /**
     * INTERNAL:
     * @param metadataAccessor
     * @param mapping
     */
    protected void processTemporal(MetadataAccessor metadataAccessor, DirectToFieldMapping mapping) {
    	XMLAccessor accessor = (XMLAccessor) metadataAccessor;
    	if (accessor.isTemporal()) {
    		String temporalType = "";
    		if (accessor.hasTemporal()) {
    			temporalType = accessor.getTemporalNode().getNodeValue();
    		}
    		processTemporal(accessor, temporalType, mapping);
    	}
    }
    
    /**
     * INTERNAL:
     * Apply unique-constraints to a given database table.
     * 
     * @param constraintsObj
     * @param dbTable
     */
    protected void processUniqueConstraints(Object[] constraints, DatabaseTable dbTable) {
    	// for each constraint
    	dbTable.addUniqueConstraint( (String[])constraints);
    }
    
    /**
     * INTERNAL:
     * Set the get and set access methods on a mapping.
     * 
     * @param attributeName 
     * @param mapping 
     * @param dmd 
     */
    public static void setAccessorMethods(String attributeName, DatabaseMapping mapping, XMLDescriptorMetadata dmd) {
    	// TODO:  should remove this method once accessors are fully implemented
    	String name = Character.toString(attributeName.charAt(0)).toUpperCase() + attributeName.substring(1, attributeName.length());
        Method[] methods = PrivilegedAccessController.getDeclaredMethods(dmd.getJavaClass());

        // for each method declared on the object...
        for (int i=0; i<methods.length; i++) {
            String methodName = methods[i].getName();
            // look for the attribute name in the method name
            if (methodName.indexOf(name) != -1) {
                // look for 'set' method
                if (methodName.indexOf(XMLConstants.SET) != -1) {
                    mapping.setSetMethodName(methodName);
                } else {
                    // 'get' or 'is' method
                    mapping.setGetMethodName(methodName);
                }
            }
        }
    }
}