EclipseLink 2.3.2, build 'v20111125-r10461' API Reference

org.eclipse.persistence.descriptors
Class ReturningPolicy

java.lang.Object
  extended by org.eclipse.persistence.descriptors.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
static class ReturningPolicy.Info
          INTERNAL:
 
Field Summary
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
ReturningPolicy()
           
 
Method Summary
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(org.eclipse.persistence.internal.helper.DatabaseField field)
          PUBLIC: Define that the field will be returned from an insert operation.
 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 addFieldForInsertReturnOnly(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 addFieldForUpdate(org.eclipse.persistence.internal.helper.DatabaseField field)
          PUBLIC: Define that the field will be returned from an update 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.
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

INSERT

protected static final int INSERT
See Also:
Constant Field Values

UPDATE

protected static final int UPDATE
See Also:
Constant Field Values

NUM_OPERATIONS

protected static final int NUM_OPERATIONS
See Also:
Constant Field Values

RETURN_ONLY

protected static final int RETURN_ONLY
See Also:
Constant Field Values

WRITE_RETURN

protected static final int WRITE_RETURN
See Also:
Constant Field Values

MAPPED

protected static final int MAPPED
See Also:
Constant Field Values

UNMAPPED

protected static final int UNMAPPED
See Also:
Constant Field Values

ALL

protected static final int ALL
See Also:
Constant Field Values

MAIN_SIZE

protected static final int MAIN_SIZE
See Also:
Constant Field Values

descriptor

protected ClassDescriptor descriptor
owner of the policy


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:


getFieldInfos

public java.util.List<ReturningPolicy.Info> getFieldInfos()
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:


copyMainFrom

protected void copyMainFrom(ReturningPolicy policy)

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.


EclipseLink 2.3.2, build 'v20111125-r10461' API Reference