org.eclipse.persistence.descriptors
Class ReturningPolicy

java.lang.Object
  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.