Package org.eclipse.persistence.descriptors

Class ReturningPolicy

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public class ReturningPolicy
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

    Purpose: Allows for INSERT or UPDATE operations to return values back into the object being written. This allows for table default values, trigger or stored procedures computed values to be set back into the object. This can be used with generated SQL on the Oracle platform using the RETURNING clause, or through stored procedures on other platforms.

    See Also:
    Serialized Form
    Since:
    TopLink 10.1.3

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ReturningPolicy.Info
      INTERNAL:

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static int ALL  
      protected ClassDescriptor descriptor
      owner of the policy
      protected java.util.Map<org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.helper.DatabaseField> fieldsNotFromDescriptor_DefaultTable
      contains all default table the returning fields that are either unmapped or mapped supplied with types.
      protected java.util.Map<org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.helper.DatabaseField> fieldsNotFromDescriptor_OtherTables
      contains all the other tables returning fields that are either unmapped or mapped supplied with types.
      protected java.util.List<ReturningPolicy.Info> infos
      Stores an object of type Info for every call to any of addField.. methods.
      protected static int INSERT  
      protected boolean isUsedToSetPrimaryKey
      indicates whether ReturningPolicy is used for generation of the PK.
      protected java.util.Collection<org.eclipse.persistence.internal.helper.DatabaseField>[][] main
      The following attributes are initialized by initialize() method.
      protected static int MAIN_SIZE  
      protected static int MAPPED  
      protected static int NUM_OPERATIONS  
      protected static int RETURN_ONLY  
      protected java.util.Map<org.eclipse.persistence.internal.helper.DatabaseTable,​java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField>>[] tableToFieldsForGenerationMap
      maps ClassDescriptor's tables into Vectors of fields to be used for call generation.
      protected static int UNMAPPED  
      protected static int UPDATE  
      protected static int WRITE_RETURN  

    • Constructor Summary

      Constructors 
      Constructor Description
      ReturningPolicy()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addCollectionToMain​(int operation, int state, java.util.Collection collection)  
      protected void addField​(org.eclipse.persistence.internal.helper.DatabaseField field, boolean isInsert, boolean isInsertModeReturnOnly, boolean isUpdate)
      INTERNAL:
      void addFieldForInsert​(java.lang.String qualifiedName)
      PUBLIC: Define that the field will be returned from an insert operation.
      void addFieldForInsert​(java.lang.String qualifiedName, java.lang.Class type)
      PUBLIC: Define that the field will be returned from an insert operation.
      void addFieldForInsert​(org.eclipse.persistence.internal.helper.DatabaseField field)
      PUBLIC: Define that the field will be returned from an insert operation.
      void addFieldForInsertReturnOnly​(java.lang.String qualifiedName)
      PUBLIC: Define that the field will be returned from an insert operation.
      void addFieldForInsertReturnOnly​(java.lang.String qualifiedName, java.lang.Class type)
      PUBLIC: Define that the field will be returned from an insert operation.
      void addFieldForInsertReturnOnly​(org.eclipse.persistence.internal.helper.DatabaseField field)
      PUBLIC: Define that the field will be returned from an insert operation.
      void addFieldForUpdate​(java.lang.String qualifiedName)
      PUBLIC: Define that the field will be returned from an update operation.
      void addFieldForUpdate​(java.lang.String qualifiedName, java.lang.Class type)
      PUBLIC: Define that the field will be returned from an update operation.
      void addFieldForUpdate​(org.eclipse.persistence.internal.helper.DatabaseField field)
      PUBLIC: Define that the field will be returned from an update operation.
      protected void addFieldToMain​(int operation, int state, org.eclipse.persistence.internal.helper.DatabaseField field)  
      protected void addMappedFieldToMain​(org.eclipse.persistence.internal.helper.DatabaseField field, ReturningPolicy.Info info)  
      protected void addUnmappedFieldToMain​(org.eclipse.persistence.internal.helper.DatabaseField field, ReturningPolicy.Info info)  
      static boolean areCollectionsEqualAsSets​(java.util.Collection col1, java.util.Collection col2)
      INTERNAL: Compares two Collections as sets (ignoring the order of the elements).
      protected void clearInitialization()  
      java.lang.Object clone()
      INTERNAL: Normally cloned when not yet initialized.
      protected void copyMainFrom​(ReturningPolicy policy)  
      protected java.util.Collection createCollection()
      INTERNAL:
      protected org.eclipse.persistence.internal.helper.DatabaseField createField​(java.lang.String qualifiedName, java.lang.Class type)
      INTERNAL:
      protected void fieldIsNotFromDescriptor​(org.eclipse.persistence.internal.helper.DatabaseField field)
      INTERNAL:
      ClassDescriptor getDescriptor()
      PUBLIC: Return the owner of the policy.
      org.eclipse.persistence.internal.helper.DatabaseField getField​(org.eclipse.persistence.internal.helper.DatabaseField field)
      INTERNAL: Returns an equal field held by ReturningPolicy, or null.
      java.util.List<ReturningPolicy.Info> getFieldInfos()
      INTERNAL:
      java.util.Vector getFieldsToGenerateInsert​(org.eclipse.persistence.internal.helper.DatabaseTable table)
      INTERNAL:
      java.util.Vector getFieldsToGenerateUpdate​(org.eclipse.persistence.internal.helper.DatabaseTable table)
      INTERNAL:
      java.util.Collection<org.eclipse.persistence.internal.helper.DatabaseField> getFieldsToMergeInsert()
      INTERNAL:
      java.util.Collection<org.eclipse.persistence.internal.helper.DatabaseField> getFieldsToMergeUpdate()
      INTERNAL:
      protected java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField> getVectorOfFieldsToGenerate​(int operation, org.eclipse.persistence.internal.helper.DatabaseTable table)
      INTERNAL:
      boolean hasEqualFieldInfos​(java.util.List<ReturningPolicy.Info> infosToCompare)
      INTERNAL: Used for testing only
      boolean hasEqualFieldInfos​(ReturningPolicy returningPolicyToCompare)
      INTERNAL: Used for testing only
      boolean hasEqualMains​(ReturningPolicy policy)
      INTERNAL: Both ReturningPolicies should be initialized
      void initialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL:
      protected void initializeIsUsedToSetPrimaryKey()  
      protected static boolean isThereATypeConflict​(org.eclipse.persistence.internal.helper.DatabaseField field1, org.eclipse.persistence.internal.helper.DatabaseField field2)
      INTERNAL:
      boolean isUsedToSetPrimaryKey()
      PUBLIC:
      protected java.util.Hashtable removeDuplicateAndValidateInfos​(org.eclipse.persistence.internal.sessions.AbstractSession session)  
      void setDescriptor​(ClassDescriptor descriptor)
      INTERNAL:
      void setFieldInfos​(java.util.List<ReturningPolicy.Info> infos)
      INTERNAL:
      protected void trimModifyRow​(org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow, int operation)  
      void trimModifyRowForInsert​(org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow)
      INTERNAL:
      void validationAfterDescriptorInitialization​(org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL:
      protected static boolean verifyField​(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.helper.DatabaseField field, ClassDescriptor descriptor)  
      protected boolean verifyFieldAndMapping​(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.helper.DatabaseField field)  
      protected static boolean verifyFieldAndMapping​(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.helper.DatabaseField field, ClassDescriptor descriptor, DatabaseMapping mapping)  

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • infos

        protected java.util.List<ReturningPolicy.Info> infos
        Stores an object of type Info for every call to any of addField.. methods. Should be filled out before initialize() is called: fields added after initialization are ignored.

      • main

        protected java.util.Collection<org.eclipse.persistence.internal.helper.DatabaseField>[][] main
        The following attributes are initialized by initialize() method. Contains the actual DatabaseFields to be returned. Populated during descriptor initialization using infos. Here's the order: 
         main[INSERT][RETURN_ONLY]  main[INSERT][WRITE_RETURN]  main[INSERT][MAPPED]    main[INSERT][UNMAPPED]    main[INSERT][ALL]
 main[UPDATE][RETURN_ONLY]  main[UPDATE][WRITE_RETURN]  main[UPDATE][MAPPED]    main[UPDATE][UNMAPPED]    main[UPDATE][ALL]
        After initialization main[UPDATE,WRITE_RETURN] will contain all DatabaseFields that should be returned on Update as read-write. 
         main[i][RETURN_ONLY] + main[i][WRITE_RETURN] = main[i][MAPPED]
 main[i][MAPPED] + main[i][UNMAPPED] = main[i][ALL]

      • tableToFieldsForGenerationMap

        protected java.util.Map<org.eclipse.persistence.internal.helper.DatabaseTable,​java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField>>[] tableToFieldsForGenerationMap
        maps ClassDescriptor's tables into Vectors of fields to be used for call generation. Lazily initialized array [NUM_OPERATIONS]

      • isUsedToSetPrimaryKey

        protected boolean isUsedToSetPrimaryKey
        indicates whether ReturningPolicy is used for generation of the PK.

      • fieldsNotFromDescriptor_DefaultTable

        protected java.util.Map<org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.helper.DatabaseField> fieldsNotFromDescriptor_DefaultTable
        contains all default table the returning fields that are either unmapped or mapped supplied with types.

      • fieldsNotFromDescriptor_OtherTables

        protected java.util.Map<org.eclipse.persistence.internal.helper.DatabaseField,​org.eclipse.persistence.internal.helper.DatabaseField> fieldsNotFromDescriptor_OtherTables
        contains all the other tables returning fields that are either unmapped or mapped supplied with types.

    • Constructor Detail

      • ReturningPolicy

        public ReturningPolicy()

    • Method Detail

      • getDescriptor

        public ClassDescriptor getDescriptor()
        PUBLIC: Return the owner of the policy.

      • fieldIsNotFromDescriptor

        protected void fieldIsNotFromDescriptor​(org.eclipse.persistence.internal.helper.DatabaseField field)
        INTERNAL:

      • getFieldsToGenerateInsert

        public java.util.Vector getFieldsToGenerateInsert​(org.eclipse.persistence.internal.helper.DatabaseTable table)
        INTERNAL:

      • getFieldsToGenerateUpdate

        public java.util.Vector getFieldsToGenerateUpdate​(org.eclipse.persistence.internal.helper.DatabaseTable table)
        INTERNAL:

      • setFieldInfos

        public void setFieldInfos​(java.util.List<ReturningPolicy.Info> infos)
        INTERNAL:

      • hasEqualFieldInfos

        public boolean hasEqualFieldInfos​(ReturningPolicy returningPolicyToCompare)
        INTERNAL: Used for testing only

      • hasEqualFieldInfos

        public boolean hasEqualFieldInfos​(java.util.List<ReturningPolicy.Info> infosToCompare)
        INTERNAL: Used for testing only

      • areCollectionsEqualAsSets

        public static boolean areCollectionsEqualAsSets​(java.util.Collection col1,
                                                java.util.Collection col2)
        INTERNAL: Compares two Collections as sets (ignoring the order of the elements). Note that the passed Collections are cloned. Used for testing only.

      • getVectorOfFieldsToGenerate

        protected java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField> getVectorOfFieldsToGenerate​(int operation,
                                                                                                              org.eclipse.persistence.internal.helper.DatabaseTable table)
        INTERNAL:

      • getFieldsToMergeInsert

        public java.util.Collection<org.eclipse.persistence.internal.helper.DatabaseField> getFieldsToMergeInsert()
        INTERNAL:

      • getFieldsToMergeUpdate

        public java.util.Collection<org.eclipse.persistence.internal.helper.DatabaseField> getFieldsToMergeUpdate()
        INTERNAL:

      • clone

        public java.lang.Object clone()
        INTERNAL: Normally cloned when not yet initialized. If initialized ReturningPolicy cloned then the clone should be re-initialized.
        Overrides:
        clone in class java.lang.Object

      • setDescriptor

        public void setDescriptor​(ClassDescriptor descriptor)
        INTERNAL:

      • addFieldForInsert

        public void addFieldForInsert​(java.lang.String qualifiedName)
        PUBLIC: Define that the field will be returned from an insert operation.

      • addFieldForInsert

        public void addFieldForInsert​(java.lang.String qualifiedName,
                              java.lang.Class type)
        PUBLIC: Define that the field will be returned from an insert operation. The type may be required to bind the output parameter if not known by the mapping.

      • addFieldForInsert

        public void addFieldForInsert​(org.eclipse.persistence.internal.helper.DatabaseField field)
        PUBLIC: Define that the field will be returned from an insert operation.

      • addFieldForInsertReturnOnly

        public void addFieldForInsertReturnOnly​(java.lang.String qualifiedName)
        PUBLIC: Define that the field will be returned from an insert operation. A field added with addFieldForInsertReturnOnly method is excluded from INSERT clause during SQL generation.

      • addFieldForInsertReturnOnly

        public void addFieldForInsertReturnOnly​(java.lang.String qualifiedName,
                                        java.lang.Class type)
        PUBLIC: Define that the field will be returned from an insert operation. A field added with addFieldForInsertReturnOnly method is excluded from INSERT clause during SQL generation. The type may be required to bind the output parameter if not known by the mapping.

      • addFieldForInsertReturnOnly

        public void addFieldForInsertReturnOnly​(org.eclipse.persistence.internal.helper.DatabaseField field)
        PUBLIC: Define that the field will be returned from an insert operation. A field added with addFieldForInsertReturnOnly method is excluded from INSERT clause during SQL generation.

      • addFieldForUpdate

        public void addFieldForUpdate​(java.lang.String qualifiedName)
        PUBLIC: Define that the field will be returned from an update operation.

      • addFieldForUpdate

        public void addFieldForUpdate​(java.lang.String qualifiedName,
                              java.lang.Class type)
        PUBLIC: Define that the field will be returned from an update operation. The type may be required to bind the output parameter if not known by the mapping.

      • addFieldForUpdate

        public void addFieldForUpdate​(org.eclipse.persistence.internal.helper.DatabaseField field)
        PUBLIC: Define that the field will be returned from an update operation.

      • addField

        protected void addField​(org.eclipse.persistence.internal.helper.DatabaseField field,
                        boolean isInsert,
                        boolean isInsertModeReturnOnly,
                        boolean isUpdate)
        INTERNAL:

      • isThereATypeConflict

        protected static boolean isThereATypeConflict​(org.eclipse.persistence.internal.helper.DatabaseField field1,
                                              org.eclipse.persistence.internal.helper.DatabaseField field2)
        INTERNAL:

      • createField

        protected org.eclipse.persistence.internal.helper.DatabaseField createField​(java.lang.String qualifiedName,
                                                                            java.lang.Class type)
        INTERNAL:

      • createCollection

        protected java.util.Collection createCollection()
        INTERNAL:

      • addFieldToMain

        protected void addFieldToMain​(int operation,
                              int state,
                              org.eclipse.persistence.internal.helper.DatabaseField field)

      • addCollectionToMain

        protected void addCollectionToMain​(int operation,
                                   int state,
                                   java.util.Collection collection)

      • addMappedFieldToMain

        protected void addMappedFieldToMain​(org.eclipse.persistence.internal.helper.DatabaseField field,
                                    ReturningPolicy.Info info)

      • addUnmappedFieldToMain

        protected void addUnmappedFieldToMain​(org.eclipse.persistence.internal.helper.DatabaseField field,
                                      ReturningPolicy.Info info)

      • removeDuplicateAndValidateInfos

        protected java.util.Hashtable removeDuplicateAndValidateInfos​(org.eclipse.persistence.internal.sessions.AbstractSession session)

      • initialize

        public void initialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL:

      • hasEqualMains

        public boolean hasEqualMains​(ReturningPolicy policy)
        INTERNAL: Both ReturningPolicies should be initialized

      • trimModifyRowForInsert

        public void trimModifyRowForInsert​(org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow)
        INTERNAL:

      • trimModifyRow

        protected void trimModifyRow​(org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow,
                             int operation)

      • isUsedToSetPrimaryKey

        public boolean isUsedToSetPrimaryKey()
        PUBLIC:

      • clearInitialization

        protected void clearInitialization()

      • initializeIsUsedToSetPrimaryKey

        protected void initializeIsUsedToSetPrimaryKey()

      • verifyFieldAndMapping

        protected boolean verifyFieldAndMapping​(org.eclipse.persistence.internal.sessions.AbstractSession session,
                                        org.eclipse.persistence.internal.helper.DatabaseField field)

      • verifyFieldAndMapping

        protected static boolean verifyFieldAndMapping​(org.eclipse.persistence.internal.sessions.AbstractSession session,
                                               org.eclipse.persistence.internal.helper.DatabaseField field,
                                               ClassDescriptor descriptor,
                                               DatabaseMapping mapping)

      • verifyField

        protected static boolean verifyField​(org.eclipse.persistence.internal.sessions.AbstractSession session,
                                     org.eclipse.persistence.internal.helper.DatabaseField field,
                                     ClassDescriptor descriptor)

      • validationAfterDescriptorInitialization

        public void validationAfterDescriptorInitialization​(org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL:

      • getField

        public org.eclipse.persistence.internal.helper.DatabaseField getField​(org.eclipse.persistence.internal.helper.DatabaseField field)
        INTERNAL: Returns an equal field held by ReturningPolicy, or null.