diff --git a/src/main/java/org/mybatis/dynamic/sql/SqlColumn.java b/src/main/java/org/mybatis/dynamic/sql/SqlColumn.java
index b3dcf9513..d8f9dc56e 100644
--- a/src/main/java/org/mybatis/dynamic/sql/SqlColumn.java
+++ b/src/main/java/org/mybatis/dynamic/sql/SqlColumn.java
@@ -33,7 +33,7 @@
* the {@link SqlTable} the column is a part of.
*
*
The class can be extended if you wish to associate additional attributes with a column for your
- * own purposes. Extending the class is a bit more challenging than you might expect because you will need to
+ * own purposes. Extending the class is a bit more challenging than you might expect because you may need to
* handle the covariant types for many methods in {@code SqlColumn}. Additionally, many methods in {@code SqlColumn}
* create new instances of the class in keeping with the library's primary strategy of immutability. You will also
* need to ensure that these methods create instances of your extended class, rather than the base {@code SqlColumn}
@@ -44,16 +44,18 @@
*
Create a class that extends {@link SqlColumn}
* In your extended class, create a static builder class that extends {@link SqlColumn.AbstractBuilder}
* Add your desired attributes to the class and the builder
- * In your extended class, override the {@link SqlColumn#copyBuilder()} method and return a new instance of
- * your builder with all attributes set. You should call the
+ * You MUST override the {@link SqlColumn#copyBuilder()} method and return a new instance of
+ * your builder with all attributes set. In the overridden method you should call the superclass
* {@link SqlColumn#populateBaseBuilder(AbstractBuilder)} method
- * to set the attributes from {@code SqlColumn}, then populate your extended attributes.
+ * to set the attributes from the base {@code SqlColumn}, then populate your extended attributes. During normal
+ * usage, the library may create additional instances of your class. If you do not override the
+ * {@link SqlColumn#copyBuilder()} method properly, then your extended attributes will be lost.
*
- * You MUST override the following methods. These methods are used with regular operations in the library.
- * If you do not override these methods, it is likely that your extended attributes will be lost during
- * regular usage. For example, if you do not override the {@code as} method and a user calls the method to
- * apply an alias, then the base {@code SqlColumn} class would create a new instance of {@code SqlColumn}, NOT
- * your extended class.
+ * You MAY override the following methods. These methods are used with regular operations in the library and
+ * create new instances of the class. However, these methods are not typically chained, so losing the specific
+ * type may not be a problem. If you want to preserve the type, then you can override these methods
+ * to specify the covariant return type. See below for usage of the {@link SqlColumn#cast(SqlColumn)} method
+ * to make it easier to override these methods.
*
* - {@link SqlColumn#as(String)}
* - {@link SqlColumn#asCamelCase()}
@@ -63,8 +65,10 @@
*
* You SHOULD override the following methods. These methods can be used to add additional attributes to a
* column by creating a new instance with a specified attribute set. These methods are used during the
- * construction of columns. If you do not override these methods, and a user calls them, then a new
- * {@code SqlColumn} will be created that does not contain your extended attributes.
+ * construction of columns. If you do not override these methods, and a user calls them, then the specific type
+ * will be lost. If you want to preserve the type, then you can override these methods
+ * to specify the covariant return type. See below for usage of the {@link SqlColumn#cast(SqlColumn)} method
+ * to make it easier to override these methods.
*
* - {@link SqlColumn#withJavaProperty(String)}
* - {@link SqlColumn#withRenderingStrategy(RenderingStrategy)}
@@ -88,7 +92,7 @@
* }
*
*
- * The test code for this library contains an example of a proper extension of this class.
+ *
The test code for this library contains an example of a fully executed extension of this class.
*
* @param the Java type associated with the column
*/
@@ -164,7 +168,7 @@ public Optional javaProperty() {
*/
@Override
public SqlColumn descending() {
- return cast(copyBuilder().withDescendingPhrase(" DESC").build()); //$NON-NLS-1$
+ return copyBuilder().withDescendingPhrase(" DESC").build(); //$NON-NLS-1$
}
/**
@@ -177,7 +181,7 @@ public SqlColumn descending() {
*/
@Override
public SqlColumn as(String alias) {
- return cast(copyBuilder().withAlias(alias).build());
+ return copyBuilder().withAlias(alias).build();
}
/**
@@ -188,7 +192,7 @@ public SqlColumn as(String alias) {
* @return a new column that will be rendered with the specified table qualifier
*/
public SqlColumn qualifiedWith(String tableQualifier) {
- return cast(copyBuilder().withTableQualifier(tableQualifier).build());
+ return copyBuilder().withTableQualifier(tableQualifier).build();
}
/**
@@ -203,9 +207,9 @@ public SqlColumn qualifiedWith(String tableQualifier) {
* @return a new column aliased with a camel case version of the column name
*/
public SqlColumn asCamelCase() {
- return cast(copyBuilder()
+ return copyBuilder()
.withAlias("\"" + StringUtilities.toCamelCase(name) + "\"") //$NON-NLS-1$ //$NON-NLS-2$
- .build());
+ .build();
}
@Override
@@ -318,6 +322,14 @@ public SqlColumn withJavaProperty(String javaProperty) {
return cast(copyBuilder().withJavaProperty(javaProperty).build());
}
+ /**
+ * Create a new Builder, then populate all attributes in the builder with current values.
+ *
+ * This method is used to create copies of the class during normal operations (e.g. when calling the
+ * {@link SqlColumn#as(String)} method). Any subclass of {@code SqlColumn} MUST override this method.
+ *
+ * @return a new Builder instance with all current values populated
+ */
protected AbstractBuilder copyBuilder() {
return populateBaseBuilder(new Builder<>());
}