HHH-8163 - Deprecate @IndexColumn and add @ListIndexBase

documentation/src/main/docbook/manual/en-US/content/collection_mapping.xml

@@ -584,13 +584,16 @@ public class Order {
         </example>
 
         <note>
-          <para>We recommend you to convert <classname>the legacy
+            <para>
-          @org.hibernate.annotations.IndexColumn</classname> usages to
+                We recommend you to convert the legacy <classname>@org.hibernate.annotations.IndexColumn</classname>
-          <classname>@OrderColumn</classname> unless you are making use of the
+                usages to the JPA standard <classname>@javax.persistence.OrderColumn</classname>.
-          base property. The <literal>base</literal> property lets you define
+            </para>
-          the index value of the first element (aka as base index). The usual
+            <para>
-          value is <literal>0</literal> or <literal>1</literal>. The default
+                If you are leveraging a custom list index base (maybe currently using the
-          is 0 like in Java.</para>
+                <methodname>org.hibernate.annotations.IndexColumn.literal</methodname> attribute), you can
+                specify this using the <classname>@org.hibernate.annotations.ListIndexBase</classname> in conjunction
+                with <classname>@javax.persistence.OrderColumn</classname>.  The default base is 0 like in Java.
+            </para>
         </note>
 
         <para>Looking again at the Hibernate mapping file equivalent, the

hibernate-core/src/main/java/org/hibernate/cfg/AnnotationBinder.java

@@ -111,6 +111,7 @@ import org.hibernate.annotations.GenericGenerators;
 import org.hibernate.annotations.Index;
 import org.hibernate.annotations.LazyToOne;
 import org.hibernate.annotations.LazyToOneOption;
+import org.hibernate.annotations.ListIndexBase;
 import org.hibernate.annotations.ManyToAny;
 import org.hibernate.annotations.MapKeyType;
 import org.hibernate.annotations.NaturalId;
@@ -1708,6 +1709,9 @@ public final class AnnotationBinder {
 							entityBinder.getSecondaryTables(),
 							mappings
 					);
+					if ( property.isAnnotationPresent( ListIndexBase.class ) ) {
+						indexColumn.setBase( ( property.getAnnotation( ListIndexBase.class ) ).value() );
+					}
 				}
 				else {
 					//if @IndexColumn is not there, the generated IndexColumn is an implicit column and not used.

hibernate-core/src/main/java/org/hibernate/cfg/IndexColumn.java

@@ -77,17 +77,27 @@ public class IndexColumn extends Ejb3Column {
 		this.base = base;
 	}
 
-	//JPA 2 @OrderColumn processing
+	/**
+	 * JPA 2 {@link OrderColumn @OrderColumn} processing.
+	 *
+	 * @param ann The OrderColumn annotation instance
+	 * @param propertyHolder Information about the property
+	 * @param inferredData Yeah, right.  Uh...
+	 * @param secondaryTables Any secondary tables available.
+	 * @param mappings The mappings being built.
+	 *
+	 * @return The index column
+	 */
 	public static IndexColumn buildColumnFromAnnotation(
 			OrderColumn ann,
 			PropertyHolder propertyHolder,
 			PropertyData inferredData,
 			Map<String, Join> secondaryTables,
 			Mappings mappings) {
-		IndexColumn column;
+		final IndexColumn column;
 		if ( ann != null ) {
-			String sqlType = BinderHelper.isEmptyAnnotationValue( ann.columnDefinition() ) ? null : ann.columnDefinition();
+			final String sqlType = BinderHelper.isEmptyAnnotationValue( ann.columnDefinition() ) ? null : ann.columnDefinition();
-			String name = BinderHelper.isEmptyAnnotationValue( ann.name() ) ? inferredData.getPropertyName() + "_ORDER" : ann.name();
+			final String name = BinderHelper.isEmptyAnnotationValue( ann.name() ) ? inferredData.getPropertyName() + "_ORDER" : ann.name();
 			//TODO move it to a getter based system and remove the constructor
 // The JPA OrderColumn annotation defines no table element...
 //			column = new IndexColumn(
@@ -110,16 +120,25 @@ public class IndexColumn extends Ejb3Column {
 		return column;
 	}
 
-	//legacy @IndexColumn processing
+	/**
+	 * Legacy {@link IndexColumn @IndexColumn} processing.
+	 *
+	 * @param ann The IndexColumn annotation instance
+	 * @param propertyHolder Information about the property
+	 * @param inferredData Yeah, right.  Uh...
+	 * @param mappings The mappings being built.
+	 *
+	 * @return The index column
+	 */
 	public static IndexColumn buildColumnFromAnnotation(
 			org.hibernate.annotations.IndexColumn ann,
 			PropertyHolder propertyHolder,
 			PropertyData inferredData,
 			Mappings mappings) {
-		IndexColumn column;
+		final IndexColumn column;
 		if ( ann != null ) {
-			String sqlType = BinderHelper.isEmptyAnnotationValue( ann.columnDefinition() ) ? null : ann.columnDefinition();
+			final String sqlType = BinderHelper.isEmptyAnnotationValue( ann.columnDefinition() ) ? null : ann.columnDefinition();
-			String name = BinderHelper.isEmptyAnnotationValue( ann.name() ) ? inferredData.getPropertyName() : ann.name();
+			final String name = BinderHelper.isEmptyAnnotationValue( ann.name() ) ? inferredData.getPropertyName() : ann.name();
 			//TODO move it to a getter based system and remove the constructor
 			column = new IndexColumn(
 					false, sqlType, 0, 0, 0, name, ann.nullable(),

hibernate-core/src/test/java/org/hibernate/test/annotations/array/Contest.java

@@ -1,5 +1,6 @@
 //$Id$
 package org.hibernate.test.annotations.array;
+
 import javax.persistence.CascadeType;
 import javax.persistence.ElementCollection;
 import javax.persistence.Entity;
@@ -8,7 +9,7 @@ import javax.persistence.Id;
 import javax.persistence.OneToMany;
 import javax.persistence.OrderColumn;
 
-import org.hibernate.annotations.IndexColumn;
+import org.hibernate.annotations.ListIndexBase;
 
 /**
  * @author Emmanuel Bernard
@@ -40,7 +41,8 @@ public class Contest {
 	}
 	
 	@ElementCollection
-	@IndexColumn(name = "pos", base=1) //legacy + base
+	@OrderColumn
+	@ListIndexBase( 1 )
 	public Month[] getHeldIn() {
 		return heldIn;
 	}

hibernate-core/src/test/java/org/hibernate/test/annotations/indexcoll/Wardrobe.java

@@ -1,5 +1,5 @@
-//$Id$
 package org.hibernate.test.annotations.indexcoll;
+
 import java.util.List;
 import javax.persistence.CascadeType;
 import javax.persistence.Entity;
@@ -7,8 +7,9 @@ import javax.persistence.GeneratedValue;
 import javax.persistence.Id;
 import javax.persistence.JoinColumn;
 import javax.persistence.OneToMany;
+import javax.persistence.OrderColumn;
 
-import org.hibernate.annotations.IndexColumn;
+import org.hibernate.annotations.ListIndexBase;
 
 /**
  * @author Emmanuel Bernard
@@ -34,8 +35,9 @@ public class Wardrobe {
 	 * not recommended).
 	 */
 	@OneToMany(cascade = CascadeType.ALL)
-	@IndexColumn(name = "drawer_position", base = 1)
 	@JoinColumn(name = "wardrobe_id", nullable = false)
+	@OrderColumn( name = "drawer_position" )
+	@ListIndexBase( 1 )
 	public List<Drawer> getDrawers() {
 		return drawers;
 	}

hibernate-core/src/test/java/org/hibernate/test/propertyref/DoesNotWork.java

@@ -30,12 +30,14 @@ import javax.persistence.EmbeddedId;
 import javax.persistence.Entity;
 import javax.persistence.JoinColumn;
 import javax.persistence.JoinTable;
+import javax.persistence.OrderColumn;
 import javax.persistence.Table;
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
 
 import org.hibernate.annotations.IndexColumn;
+import org.hibernate.annotations.ListIndexBase;
 
 /**
  * @author Steve Ebersole
@@ -58,7 +60,8 @@ public class DoesNotWork implements Serializable {
 			joinColumns = @JoinColumn(name = "text_id", referencedColumnName = "production_credits_tid")
 	)
 	@Column(name = "text_part", insertable = false, updatable = false)
-	@IndexColumn(name = "seq_no", base = 1)
+	@OrderColumn( name = "seq_no" )
+	@ListIndexBase(1)
 	private List<String> globalNotes = new ArrayList<String>();
 
 	public DoesNotWork() {