Fix #96 Support explicit inclusion/exlusion of properties

README.md

@@ -53,7 +53,7 @@ For older versions and a *change log* please see the [release history page].
 PojoBuilder *binaries* are available for download at [Sonatype OSS Maven Repository] and [Maven Central].
 
 If you don't use any build automation tool that supports maven repos,
-you might want to download the `pojobuilder-*-jar-with-dependencies.jar` to get PojoBuilder complete with all dependent libraries included.
+you might want to download the `pojobuilder-3.4.0-jar-with-dependencies.jar` to get PojoBuilder complete with all dependent libraries included.
 
 How To Use
 ----------
@@ -229,6 +229,26 @@ The following elements of [@GeneratePojoBuilder] can be used to configure the ou
   builder interface (see above).
   For an example please see [`Recipient.java`], [`Builder.java`] and [`RecipientBuilder.java`].
   Default is `false`.
+* **includeProperties=<String[]>**
+  specifies which of the pojo's properties will be included into the generated builder. All properties that match any
+  property pattern in the specified array will be included. All other non-mandatory properties will be excluded.
+  Mandatory properties are those which are passed as constructor or factory method arguments. They will never be
+  excluded, neither explicitly nor implicitly.  
+  The property pattern consists of a name pattern followed by an optional type pattern.  
+  The syntax is `<name pattern>[:<type pattern&gt].` The pattern supports the asterisk `*`
+  wildcard character that matches any character.  
+  For an example please see [`InputSourceFactory.java`] and [`InputSourceBuilder.java`].
+  Default is `*`.
+* **excludeProperties=<String[]>**
+  specifies which of the pojo's properties will be excluded from the generated builder. All property that match any
+  property pattern in the specified array will be excluded, except those that are mandatory. Mandatory properties are
+  those which are passed as constructor or factory method arguments. They will never be excluded, neither explicitly
+  nor implicitly.
+  The property pattern consists of a name pattern followed by an optional type pattern.
+  The syntax is `<name pattern>[:<type pattern&gt].` The pattern supports the asterisk `*`
+  wildcard character that matches any character.  
+  For an example please see [`CalendarFactory.java`] and [`GregorianCalendarBuilder.java`].
+  Default is the empty array.  
 * **withGenerationGap=<boolean>**
   specifies whether the [generation gap pattern] is used. If enabled, this
   will generate two classes (instead of one), of which one contains the
@@ -326,7 +346,7 @@ The `javac` compiler will auto-detect the presence of PojoBuilder if `pojobuilde
 
 For example:
 
-    javac -cp pojobuilder-3.3.2-jar-with-dependencies.jar Contact.java
+    javac -cp pojobuilder-3.4.0-jar-with-dependencies.jar Contact.java
 
 will generate a `ContactBuilder` if `Contact` is annotated with `@GeneratePojoBuilder`.
 
@@ -339,7 +359,7 @@ Add the following to your project's `pom.xml` to configure the PojoBuilder annot
 	<dependency>
 		<groupId>net.karneim</groupId>
 		<artifactId>pojobuilder</artifactId>
-		<version>3.3.2</version>
+		<version>3.4.0</version>
 		<!-- 'provided' scope because this is only needed during compilation -->
 		<scope>provided</scope>
 	</dependency>
@@ -361,7 +381,7 @@ repositories {
 }
 
 dependencies {
-  compile 'net.karneim:pojobuilder:3.3.2'
+  compile 'net.karneim:pojobuilder:3.4.0'
 }
 ```
 Please note that this not only adds the PojoBuilder and its dependencies to your compile-time class path but also to your run-time class path.
@@ -379,7 +399,7 @@ configurations {
 }
 
 dependencies {
-  codeGeneration 'net.karneim:pojobuilder:3.3.2'
+  codeGeneration 'net.karneim:pojobuilder:3.4.0'
 }
 compileJava.classpath += configurations.codeGeneration
 compileTestJava.classpath += configurations.codeGeneration
@@ -430,7 +450,7 @@ Do the following to enable PojoBuilder for your Eclipse project:
 * Open your project's properties dialog
 * Navigate to "Java Build Path" tree node
 * Open the "Libraries" tab
-* Add `pojobuilder-3.3.2-annotations.jar` to your project classpath
+* Add `pojobuilder-3.4.0-annotations.jar` to your project classpath
 * Navigate to "Java Compiler / Annotation Processing" tree node
 * Check "Enable project specific settings"
 * Check "Enable annotation processing"
@@ -439,7 +459,7 @@ Do the following to enable PojoBuilder for your Eclipse project:
 * Navigate to "Java Compiler / Annotation Processing / Factory Path" tree node
 * Check "Enable project specific settings"
 * Click "Add JARs..."
-* Add `pojobuiler-3.3.2-jar-with-dependencies.jar`
+* Add `pojobuiler-3.4.0-jar-with-dependencies.jar`
 * Click "OK"
 
 How To Build
@@ -476,6 +496,10 @@ If you want to compile this project's sources yourself you can use Gradle (see [
 [`UserBuilder.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/UserBuilder.java
 [`UrlBuilder.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/UrlBuilder.java
 [`FileBuilder.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/FileBuilder.java
+[`InputSourceFactory.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/InputSourceFactory.java
+[`InputSourceBuilder.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/InputSourceBuilder.java
+[`CalendarFactory.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/CalendarFactory.java
+[`GregorianCalendarBuilder.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/GregorianCalendarBuilder.java
 [`Player.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/Player.java
 [`PlayerBuilder.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/PlayerBuilder.java
 [`AbstractPlayerBuilder.java`]: http://github.com/mkarneim/pojobuilder/blob/master/src/testdata/java/samples/AbstractPlayerBuilder.java

build.gradle

@@ -40,7 +40,7 @@ apply plugin: 'com.github.kt3k.coveralls'
 
 group = 'net.karneim'
 archivesBaseName = "pojobuilder"
-version = '3.4.0-SNAPSHOT'
+version = '3.4.0'
 sourceCompatibility = 1.6
 
 repositories.mavenCentral()

src/main/java/net/karneim/pojobuilder/GeneratePojoBuilder.java

@@ -15,6 +15,7 @@
   public final String DEFAULT_PACKAGE = "*";
   public final String DEFAULT_SETTER_NAME = "with*";
   public final String DEFAULT_FACTORY_METHOD = "";
+  public final String DEFAULT_INCLUSION_PATTERN = "*";
 
   /**
    * Specifies the base class of the generated builder.
@@ -24,8 +25,8 @@
   Class<?> withBaseclass() default Object.class;
 
   /**
-   * Specifies the generic builder interface of the generated builder. This interface must declare
-   * exactly one type parameter and a <code>build()</code> method having this type as return type.
+   * Specifies the generic builder interface of the generated builder. This interface must declare exactly one type
+   * parameter and a <code>build()</code> method having this type as return type.
    * <p>
    * For example:
    * 
@@ -37,28 +38,25 @@
    * </code>
    * </pre>
    * 
-   * @return the generic interface of the generated builder or {@link Void}, if no interface is
-   *         specified
+   * @return the generic interface of the generated builder or {@link Void}, if no interface is specified
    */
   Class<?> withBuilderInterface() default Void.class;
 
   /**
-   * Specifies whether the generated builder should define builder-based setter-methods using the
-   * builder interface.
+   * Specifies whether the generated builder should define builder-based setter-methods using the builder interface.
    * <p>
-   * When set to <code>true</code>, the {@link GeneratePojoBuilder#withBuilderInterface()} must
-   * specify a valid interface.
+   * When set to <code>true</code>, the {@link GeneratePojoBuilder#withBuilderInterface()} must specify a valid
+   * interface.
    * 
    * @return whether the generated builder should define builder-based setter-methods
    */
   boolean withBuilderProperties() default false;
 
   /**
-   * Specifies whether the generated builder should define optional-based setter-methods using the
-   * specified 'Optional' type.
+   * Specifies whether the generated builder should define optional-based setter-methods using the specified 'Optional'
+   * type.
    * <p>
-   * The 'Optional' type can have any name but must be interface-compatible with the following
-   * interface:
+   * The 'Optional' type can have any name but must be interface-compatible with the following interface:
    * 
    * <pre>
    * <code>
@@ -71,60 +69,58 @@
    * 
    * where T is the generic type parameter matching the property's type.
    * <p>
-   * Examples are Google Guava's com.google.common.base.Optional and java.util.Optional introduced
-   * with Java 8.
+   * Examples are Google Guava's com.google.common.base.Optional and java.util.Optional introduced with Java 8.
    * 
-   * @return the 'Optional' type used for generating the optional-based setter-methods, or
-   *         {@link Void} if no optional-based setter-methods should be generated
+   * @return the 'Optional' type used for generating the optional-based setter-methods, or {@link Void} if no
+   *         optional-based setter-methods should be generated
    */
   Class<?> withOptionalProperties() default Void.class;
 
   /**
-   * Specifies the name of the generated builder. An asterisk will be replaced with the pojos simple
-   * name. Default is "*Builder".
+   * Specifies the name of the generated builder. An asterisk will be replaced with the pojos simple name. Default is
+   * "*Builder".
    * 
    * @return the name of the generated builder
    */
   String withName() default DEFAULT_NAME;
 
   /**
-   * Specifies the name pattern of the generated setter-methods. An asterisk will be replaced with
-   * the property's original name. Default is "with*".
+   * Specifies the name pattern of the generated setter-methods. An asterisk will be replaced with the property's
+   * original name. Default is "with*".
    * 
    * @return the name pattern of the generated setter-methods.
    */
   String withSetterNamePattern() default DEFAULT_SETTER_NAME;
 
   /**
-   * Specifies the package of the generated builder. An asterisk will be replaced with the pojos
-   * package. Default is "*".
+   * Specifies the package of the generated builder. An asterisk will be replaced with the pojos package. Default is
+   * "*".
    * 
    * @return the package of the generated builder
    */
   String intoPackage() default DEFAULT_PACKAGE;
 
   /**
-   * Specifies whether the generation gap pattern is used. If enabled this will generate two classes
-   * (instead of one), of which one contains the generated code. The other class is for handwritten
-   * code. To prevent it from being overwritten please move it out of the generated-sources folder.
-   * Default is "false".
+   * Specifies whether the generation gap pattern is used. If enabled this will generate two classes (instead of one),
+   * of which one contains the generated code. The other class is for handwritten code. To prevent it from being
+   * overwritten please move it out of the generated-sources folder. Default is "false".
    * 
    * @return <code>true</code> if the generation gap should be used
    */
   boolean withGenerationGap() default false;
 
   /**
-   * Specifies whether a copy method should be generated. The copy method will take an instance of
-   * the built class and will copy all its fields into the builder. This allows it to easily change
-   * one or more fields of immutable objects.
+   * Specifies whether a copy method should be generated. The copy method will take an instance of the built class and
+   * will copy all its fields into the builder. This allows it to easily change one or more fields of immutable objects.
    * 
    * @return <code>true</code> if a copy method should be generated
    */
   boolean withCopyMethod() default false;
 
   /**
-   * Specifies the name of a static factory method added to the builder. An asterisk will be
-   * replaced by the pojos simple name. Default is "" meaning not to generate this method.
+   * Specifies the name of a static factory method added to the builder. An asterisk will be replaced by the pojos
+   * simple name. Default is "" meaning not to generate this method.
+   * 
    * <pre>
    * <code>
    * public class MyPojoBuilder {
@@ -140,10 +136,9 @@
   String withFactoryMethod() default DEFAULT_FACTORY_METHOD;
 
   /**
-   * Specifies the validator class that should be used to validate the created pojo. The class must
-   * define a <code>validate</code> method having one parameter that is compatible with the pojo's
-   * type. If the validation fails, the method must throw some runtime exception (or one of its
-   * subclasses).
+   * Specifies the validator class that should be used to validate the created pojo. The class must define a
+   * <code>validate</code> method having one parameter that is compatible with the pojo's type. If the validation fails,
+   * the method must throw some runtime exception (or one of its subclasses).
    * <p>
    * This is an example of how a validator could look like:
    * 
@@ -162,4 +157,38 @@
    * @return the validator's class, or {@link Void}, if no validator should be used.
    */
   Class<?> withValidator() default Void.class;
+
+  /**
+   * Specifies which of the pojo's properties will be included into the generated builder. All properties that match any
+   * property pattern in the specified array will be included. All other non-mandatory properties will be excluded.
+   * Mandatory properties are those which are passed as constructor or factory method arguments. They will never be
+   * excluded, neither explicitly nor implicitly.
+   * <p>
+   * The property pattern consists of a name pattern followed by an optional type pattern.
+   * <p>
+   * The syntax is <code>&lt;name pattern&gt;[:&lt;type pattern&gt].</code> The pattern supports the asterisk '*'
+   * wildcard character that matches any character.
+   * <p>
+   * Default is '*'.
+   * 
+   * @return the inclusion patterns
+   */
+  String[] includeProperties() default {DEFAULT_INCLUSION_PATTERN};
+
+  /**
+   * Specifies which of the pojo's properties will be excluded from the generated builder. All property that match any
+   * property pattern in the specified array will be excluded, except those that are mandatory. Mandatory properties are
+   * those which are passed as constructor or factory method arguments. They will never be excluded, neither explicitly
+   * nor implicitly.
+   * <p>
+   * The property pattern consists of a name pattern followed by an optional type pattern.
+   * <p>
+   * The syntax is <code>&lt;name pattern&gt;[:&lt;type pattern&gt].</code> The pattern supports the asterisk '*'
+   * wildcard character that matches any character.
+   * <p>
+   * Default is the empty array.
+   * 
+   * @return the exclusion patterns
+   */
+  String[] excludeProperties() default {};
 }

src/main/java/net/karneim/pojobuilder/PojoBuilderException.java

@@ -0,0 +1,27 @@
+package net.karneim.pojobuilder;
+
+public class PojoBuilderException extends RuntimeException {
+
+  private static final long serialVersionUID = 1L;
+
+  public PojoBuilderException() {
+    super();
+  }
+
+  public PojoBuilderException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+    super(message, cause, enableSuppression, writableStackTrace);
+  }
+
+  public PojoBuilderException(String message, Throwable cause) {
+    super(message, cause);
+  }
+
+  public PojoBuilderException(String message) {
+    super(message);
+  }
+
+  public PojoBuilderException(Throwable cause) {
+    super(cause);
+  }
+
+}

src/main/java/net/karneim/pojobuilder/analysis/AnalysisException.java

@@ -1,7 +1,9 @@
 package net.karneim.pojobuilder.analysis;
 
+import net.karneim.pojobuilder.PojoBuilderException;
+
 @SuppressWarnings("serial")
-public class AnalysisException extends RuntimeException {
+public class AnalysisException extends PojoBuilderException {
 
   public AnalysisException(String message) {
     super(message);