pojobuilder下载 - pojobuilder源码下载

PojoBuilder - Pojo Builder 的代码生成器

作者：迈克尔·卡尼姆

项目主页：http://github.com/mkarneim/pojobuilder

关于

PojoBuilder Generator 是一个符合 Java 6 的注释处理器，可为 POJO（普通旧 Java 对象）生成流畅的构建器类。

生成的构建器提供

一个流畅的接口，用于以类似 DSL 的方式指定 pojo 属性的值
以及一个“build()”方法，用于使用这些值创建新的 pojo 实例。

以下是如何使用代码生成的 pojo 构建器的示例：

	Contact james = new ContactBuilder ()
		. withSurname ( "Bond" )
		. withFirstname ( "James" )
		. withEmail ( "[email protected]" )
		. build ();

构建器非常有用，例如，构建测试数据，您只想设置相关的数据属性。

欲了解更多信息

测试数据构建器请参阅 http://c2.com/cgi/wiki?TestDataBuilder 和 http://www.natpryce.com/articles/000714.html。
构建器模式请参阅http://en.wikipedia.org/wiki/Builder_pattern。
流畅的界面请参阅http://www.martinfowler.com/bliki/FluentInterface.html

许可证和依赖项

位于“src”目录中的源代码位于公共域中。有关更多信息，请阅读复制文件。

PojoBuilder 是一个纯代码生成器。它不会向您的项目添加任何运行时依赖项。

但是，PojoBuilder 将以下编译时依赖项添加到您的项目中，该项目有自己的许可证：

JavaWriter 2.5.0（参见许可证）

下载

PojoBuilder 是开源的。源代码可在 http://github.com/mkarneim/pojobuilder 获取。对于旧版本和更改日志，请参阅发布历史记录页面。

PojoBuilder二进制文件可从 Sonatype OSS Maven 存储库和 Maven Central 下载。

如果您不使用任何支持 Maven 存储库的构建自动化工具，您可能需要下载pojobuilder-4.3.0-jar-with-dependencies.jar以获得包含所有依赖库的完整 PojoBuilder。

如何使用

PojoBuilder 生成器使用注释处理器为您生成 pojo 构建器。您可以使用以下选项来触发代码生成：

通过注释 pojo 的构造函数
通过注释 pojo 类
通过注释工厂方法

注释构造函数

要为 pojo 生成构建器类，您可以使用@GeneratePojoBuilder注释其构造函数之一。

让我们看一下下面的 pojo 示例：

 public class Contact {
  private final String surname ;
  private final String firstname ;
  private String email ;

  @ GeneratePojoBuilder
  public Contact ( String surname , String firstname ) {
    this . surname = surname ;
    this . firstname = firstname ;
  }

  public String getEmail () {
    return email ;
  }

  public void setEmail ( String email ) {
    this . email = email ;
  }

  public String getSurname () {
    return surname ;
  }

  public String getFirstname () {
    return firstname ;
  }
}

@GeneratePojoBuilder 注释告诉注释处理器创建一个名为ContactBuilder的新 Java 源文件。查看ContactBuilder.java以查看生成的源代码。

请注意，构造函数必须是公共的，或者以其他方式可供生成的构建器访问，例如，如果它受保护，则生成的构建器必须驻留在同一包中。

另请注意，构造函数参数名称必须与 pojo 的属性名称完全匹配。

可选的 @ConstructorProperties 注释可用于指定从构造函数参数名称到 pojo 上相应 bean 属性名称的映射（如果它们不同）。

 public class Contact {
  private final String surname ;
  private final String firstname ;
  private String email ;

  @ GeneratePojoBuilder
  @ ConstructorProperties ({ "surname" , "firstname" })
  public Contact ( String arg1 , String arg2 ) {
    this . surname = arg1 ;
    this . firstname = arg2 ;
  }

  public String getEmail () {
    return email ;
  }

  public void setEmail ( String email ) {
    this . email = email ;
  }

  public String getSurname () {
    return surname ;
  }

  public String getFirstname () {
    return firstname ;
  }
}

注释 Pojo

如果您的 pojo 没有构造函数（或公共默认构造函数），您可以使用@GeneratePojoBuilder注释其类。

让我们看一下下面的 pojo 示例：

 @ GeneratePojoBuilder
public class User {
  private String name ;
  private char [] password ;

  public String getName () {
    return name ;
  }

  public void setName ( String name ) {
    this . name = name ;
  }

  public char [] getPassword () {
    return password ;
  }

  public void setPassword ( char [] password ) {
    this . password = password ;
  }
}

查看UserBuilder.java以查看生成的源代码。

注释工厂方法

或者，如果您无权访问 pojo 的源代码，或者如果您不喜欢注释 pojo，则可以注释工厂方法：

 public class UrlFactory {

  @ GeneratePojoBuilder ( withName = "UrlBuilder" , intoPackage = "samples" )
  public static URL createUrl (
    String protocol , String host , int port , String file , URLStreamHandler handler )
      throws MalformedURLException {
    return new URL ( protocol , host , port , file , handler );
  }
}

查看UrlBuilder.java以查看生成的源代码。

请注意，工厂方法必须是public和static 的。方法参数名称必须与 pojo 属性的名称完全匹配。

可选的 @FactoryProperties 注释可用于指定从工厂方法参数名称到 pojo 上相应 bean 属性名称的映射（如果它们不同）。

 public class FileFactory {

  @ GeneratePojoBuilder ( intoPackage = "samples" )
  @ FactoryProperties ({ "path" })
  public static File createFile ( String arg1 ) {
    return new File ( arg1 );
  }
}

查看FileBuilder.java以查看生成的源代码。

注释记录

从 PojoBuilder 4.3 开始，您可以注释 Java 17 记录类型：

 @ GeneratePojoBuilder
public record MyRecord ( int x , int y , String blah ) {}

指令

@GeneratePojoBuilder 的以下元素可用于配置代码生成过程的输出。

withName=指定构建器名称的模式。星号将替换为 pojos 简单名称。例如，如果 pojo 的名称是Contact则模式Fluent*Builder的结果将变为FluentContactBuilder 。默认模式是*Builder 。
withConstructor=指定构建器构造函数的可见性。默认为Visibility.PUBLIC 。
intoPackage=指定生成的构建器的包。星号将替换为 pojos 包。例如，如果 pojo 的包是com.example ，则模式*.util的结果将变为com.example.util 。默认模式是* 。
withBaseclass=指定生成的构建器的基类。默认类是Object.class 。
withBuilderInterface=指定生成的构建器的接口。该接口必须声明一个类型参数和一个将此类型作为返回类型的构建方法。有关示例，请参阅Address.java 、 Builder.java和AddressBuilder.java 。默认值为Void.class ，这意味着不应实现任何接口。
withBuilderProperties=指定生成的构建器是否应使用构建器接口定义基于构建器的 with 方法（参见上文）。有关示例，请参阅Recipient.java 、 Builder.java和RecipientBuilder.java 。默认为false 。
includeProperties=指定 pojo 的哪些属性将包含到生成的构建器中。将包含与指定数组中的任何属性模式匹配的所有属性。所有其他非强制性属性将被排除。强制属性是作为构造函数或工厂方法参数传递的属性。他们永远不会被排除在外，无论是明确的还是隐含的。有关示例，请参阅InputSourceFactory.java和InputSourceBuilder.java 。默认为* 。
exceptProperties=指定将从生成的构建器中排除 pojo 的哪些属性。与指定数组中的任何属性模式匹配的所有属性都将被排除，强制属性除外。强制属性是作为构造函数或工厂方法参数传递的属性。他们永远不会被排除在外，无论是明确的还是隐含的。有关示例，请参阅CalendarFactory.java和GregorianCalendarBuilder.java 。默认为空数组。
withGenerationGap=指定是否使用代沟模式。如果启用，这将生成两个类（而不是一个），其中一个包含普通的构建器代码，而另一个类扩展第一个类，并且是手写代码的空模板。请将其移出 generated-sources 文件夹以防止其被覆盖。有关示例，请参阅Player.java 、 PlayerBuilder.java和AbstractPlayerBuilder.java 。默认为false 。
withCopyMethod=指定是否应生成复制方法。使用 copy 方法从给定的 pojo 实例初始化构建器的值。有关示例，请参阅TextEmail.java和TextEmailBuilder.java 。默认为false 。
withOptionalProperties=指定生成的构建器是否应使用指定的“可选”类型定义基于可选的 setter 方法。示例是 Java 8 中引入的 Google Guava 的com.google.common.base.Optional和java.util.Optional默认值为Void.class ，这意味着不会生成基于可选的 setter 方法。
withSetterNamePattern=指定生成的 setter 方法的名称模式。星号将替换为该属性的原始名称。默认with* 。
withValidator=指定用于验证创建的 pojo 的验证器类。该类必须定义一个validate方法，该方法具有与 pojo 类型兼容的一个参数。如果验证失败，该方法必须抛出一些运行时异常（或其子类之一）。有关示例，请参阅Credentials.java 、 CredentialsValidator.java和CredentialsBuilder.java 。
withFactoryMethod=指定添加到创建构建器实例的构建器类的静态工厂方法的名称。星号将替换为 pojos 简单名称。有关示例，请参阅Task.java和TaskBuilder.java 。默认为""表示不生成此方法。

默认配置和元注释

从版本 3 开始，PojoBuilder 支持元注释。也就是说，您可以将 @GeneratePojoBuilder 放置到另一个注释上，它将被继承。

优点是：

常见的 PojoBuilder 指令可以在一处共享
该注释还可以保存支持元注释的其他库的指令，将它们全部绑定到一个有意义的注释中以在您的应用程序中使用。

以下示例定义了@AppPojo它可以在类级别应用并封装来自三个不同源（PojoBuilder、Lombok 和 JSR-305）的注释。

 @ GeneratePojoBuilder ( withName = "Fluent*Builder" )
@ lombok . experimental . Value // class-level annotation from Lombok
@ javax . annotation . concurrent . Immutable // class-level annotation from JSR-305
@ Target ({ ElementType . TYPE , ElementType . ANNOTATION_TYPE })
public @interface AppPojo {
}

这可以放置到您的每个 pojo 上：

 @ AppPojo
public class Contact {
  public String name ;
}

PojoBuilder 将根据从@AppPojo注解继承的指令生成FluentContactBuilder 。

从元注释继承的默认值可以被更多“本地” @GeneratePojoBuilder注释覆盖：

 @ AppPojo
@ GeneratePojoBuilder ( intoPackage = "builder" )
public class Contact {
  public String name ;
}

这将像以前一样生成FluentContactBuilder ，但生成到包builder中。

示例

PojoBuilder wiki 提供了一本有关使用 PojoBuilder Generator 的手册，例如用于构建用于自动化测试的特定于域的语言。

有关一些完整的代码示例，请查看 src/testdata/java/samples 文件夹。

执行

要执行 PojoBuilder 注释处理器，您只需将其放入编译时类路径中。在运行时不需要任何库，因为 PojoBuilder 注释的保留策略是CLASS 。

以下是有关如何运行 PojoBuilder 的简要说明列表

javac 工具
梅文
摇篮
Ant的javac任务
蚀。

使用Javac

如果类路径中包含pojobuilder-*.jar javac编译器将自动检测 PojoBuilder 的存在。

例如：

 javac -cp pojobuilder-4.3.0-jar-with-dependencies.jar Contact.java

如果Contact用@GeneratePojoBuilder注释，将生成一个ContactBuilder 。

有关详细信息，请参阅 javac 文档。

使用Maven

将以下内容添加到项目的pom.xml中以配置 PojoBuilder 注释处理器。

 
	net.karneim
	pojobuilder
	4.3.0
	
	provided

笔记：

编译阶段会自动检测并激活PojoBuilder。
生成的源将出现在标准位置： ${project.build.directory}/generated-sources/annotations 。
如果需要将生成的源保留在target目录之外的特定目录中，请配置maven-compiler-plugin的generatedSourcesDirectory 。有关示例，请参阅示例 Maven pom。
如果您依赖增量编译，那么您可能需要使用 Maven 处理器插件。
Eclipse 用户可能希望安装 m2e-apt 来集成对 APT 生成的源的支持。

使用 Gradle

这是一个小型构建脚本，展示了如何使用 Gradle 运行 PojoBuilder 注释处理器。

apply plugin : ' java '

repositories {
  mavenCentral()
}

dependencies {
  compile ' net.karneim:pojobuilder:4.3.0 '
}

请注意，这不仅将 PojoBuilder 及其依赖项添加到编译时类路径，而且还添加到运行时类路径。

或者，您可以使用以下脚本将 PojoBuilder 仅添加到编译时类路径：

apply plugin : ' java '

repositories {
  mavenCentral()
}

configurations {
  codeGeneration
}

dependencies {
  codeGeneration ' net.karneim:pojobuilder:4.3.0 '
  compileOnly ' net.karneim:pojobuilder:4.3.0:annotations '
}
compileJava . classpath + = configurations . codeGeneration
compileTestJava . classpath + = configurations . codeGeneration

在这两种情况下，生成的源都将被放入标准的build/classes目录中。

如果你想把它们放在其他地方，只需指定目的地，如下所示：

compileJava . options . compilerArgs + = [ ' -s ' , ' src/generated/java ' ]

该 wiki 包含一个扩展的 Gradle 脚本，可以完全区分代码生成和编译任务。

还有另一个 Gradle 脚本可以为 Eclipse IDE 启用 PojoBuilder。

摇篮5.0

使用 Gradle 5.0，类路径中的任何注释处理器都不再执行。为了让pojobuilder再次工作，用annotationProcessor替换使用的依赖范围

dependencies {
  annotationProcessor ' net.karneim:pojobuilder:4.3.0 '
}

使用蚂蚁

以下是一些示例 ANT 构建脚本的代码片段，该脚本在javac任务中运行 PojoBuilder 注释处理器。

        
    ">    
    < fileset id = " libs.fileset " dir = " ${basedir}/lib " >
        < include name = " *.jar " />
    fileset >

    < path id = " class.path " >
        < fileset refid = " libs.fileset " />
    path >

    < target name = " compile " depends = " init "
            description = " Compile java sources and run annotation processor " >
    	< mkdir dir = " ${src.gen.java.dir} " />
    	< mkdir dir = " ${build.classes.dir} " />
    	< javac classpathref = " class.path " destdir = " ${build.classes.dir} " >
    		< src path = " ${src.main.java.dir} " />
    		
    		< compilerarg line = " -s ${src.gen.java.dir} " />
    	javac >
    target >