Community
Participate
Working Groups
Not sure about the name, for now will use Return (return) for now. Annotations: @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Return { boolean insert() default true; boolean update() default false; boolean insertReturnOnly() default false; String type default ""; } xsd element: <xsd:complexType name="return-written-field"> <xsd:attribute name="insert" type="xsd:boolean"/> <xsd:attribute name="update" type="xsd:boolean"/> <xsd:attribute name="insert-return-only" type="xsd:boolean"/> <xsd:attribute name="type" type="xsd:string"/> </xsd:complexType> Applied to: Each Return annotation is concerned with a single db field, therefore Return annotation could be applied to: 1) any attribute (or getter/setter) mapped to a single database field; 2) FieldTransformer (in transformation mapping). Defaults: @Return means returning of the inserted value (the most widwly-used case); @Return(update=true) - return both inserted and updated values; @Return(insertReturnOnly=true) - return the value on insert without inserting the value (for instance to return the value generated by Identity).
The insertReturnOnly value is confusing in name. I like insert and update as attributes of @Return since they qualify when the value will be returned. It seems odd that the returning policy would have a flag to indicate that we do not write it. I would think that if you wanted a value returned from INSERT without have it included in the row of the statement you would do something like: @Column(name="VAL", insertable=false) @Return private String value The insertable=false is an existing way to indicate that the value should not be included in the INSERT statement. As far as the XML goes I would like to see something like: <basic name="value"> <column name="VAL" insertable="false"/> <return> </basic>
Just to be complete: @Return means return value from INSERT @Return(insert=true) means return value from INSERT @Return(insert=true, update=false) means return value from INSERT @Return(update=true) means return value from INSERT and UPDATE @Return(insert=true, update=true) means return value from INSERT and UPDATE @Return(insert=false, update=true) means return value from UPDATE @Return(insert=false) is an error or warning since it means do not use returning policy
I find it a bit confusing that Return(update=true) will also return on Insert. Consider defining a enum for return mode values: public enum ReturnMode { INSERT, UPDATE, INSERT_AND_UPDATE } @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface Return { ReturnMode mode() default INSERT; String type default ""; }
Adding NONE value - to be used as default by other annotations including an optional @Return: public enum ReturnMode { INSERT, UPDATE, INSERT_AND_UPDATE, NONE } @SomeOtherAnnotation { ... return default Return(NONE); }
Suggestion: get rid of @Return annotation (xml element), specify ReturningPolicy with ReturnMode enum value instead; move type from @Return to @WriteTransformer. Motivation: 1. Currently can't use return default Return(NONE); have to use: return default Return(mode=NONE); in other annotation (such as @Basic) because @Return has String type; 2. Type is needed only for TransformationMapping - so let's move type from @Return into WriteTranformer: @WriteTranformer(column=@Column(name="START_TIME"), class=package.MyTimeTransformer.class, type="java.sql.Time") 3. Now that only ReturnMode is left in @Return it (@Return) is no longer required: @Basic and @Transformation will have: ReturnMode return default NONE; 4. For @Transformation a single ReturnMode (relating to all fields) is superior to supplying an individual @Return in each @WriteTransformer because all these @returns should be the same (it's impossible to have INSERT on one field and UPDATE on another). With the suggested change annotations using returning will look like: @Basic(column=@Column(name="F_NAME"), return=INSERT); @Transformation( read=@ReadTransformer(method="buildNormalHours"), write={ @WriteTranformer(column=@Column(name="START_TIME"), method="getStartTime", type="java.sql.Time"), @WriteTranformer(column=@Column(name="END_TIME"), method="getEndTime", type="java.sql.Time") }, return=INSERT, ) If returning is not used "return" method is simply dropped from the annotation (indicating that the default value NONE should be used). Accordingly in xml a single attribute in <basic> and <transformation> will be used: <xsd:attribute name="return" type="orm:return-mode default=NONE"/> where: <xsd:simpleType name="return-mode"> <xsd:restriction base="xsd:token"> <xsd:enumeration value="INSERT"/> <xsd:enumeration value="UPDATE"/> <xsd:enumeration value="INSERT_AND_UPDATE"/> <xsd:enumeration value="NONE"/> </xsd:restriction> </xsd:simpleType>
This bug has not been updated to reflect work done on this feature. Returning has been implemented in annotations but is missing in eclipselink-orm.xml. We should have full support in xml for all implemented annotations.
This will be looked at in the metadata restructuring work being slated for 2.1.
Implementation of ReturnInsert and ReturnUpdate will remain as is and available to Basic mappings only. Implementation of transformation mappings will also remain as is. Availability of return-insert and return-update through XML on basic mappings was addressed in bug 296289
The Eclipselink project has moved to Github: https://github.com/eclipse-ee4j/eclipselink
