Package io.permazen.ant

Class SchemaGeneratorTask

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
io.permazen.ant.SchemaGeneratorTask
All Implemented Interfaces:
Cloneable
public class SchemaGeneratorTask extends org.apache.tools.ant.Task
Ant task for schema XML generation and/or verification.

This task scans the configured classpath for classes with @PermazenType annotations and either writes the generated schema to an XML file, or verifies the schema matches an existing XML file.

Generation of schema XML files and the use of this task is not necessary. However, it does allow certain schema-related problems to be detected at build time instead of runtime. In particular, it can let you know if any change to your model classes requires a new Permazen schema version.

This task can also check for conflicts between the schema in question and older schema versions that may still exist in production databases. These other schema versions are specified using nested <oldschemas> elements, which work just like <fileset>'s. Conflicts are only possible when explicit storage ID's are used.

The following attributes are supported by this task:

Supported Tasks
Attribute Required? Description
mode No

Set to generate to generate a new XML file, verify to verify an existing XML file, or generate-and-verify to do both (i.e., update the schema file if necessary).

Default is verify.

file Yes

The XML file to generate or verify.

failOnError No

Whether to fail if verification fails when mode="verify" or when older schema versions are specified using nested <oldschemas> elements, which work just like <fileset>s.

Default is true.

verifiedProperty No

The name of an ant property to set to true or false depending on whether verification succeeded or failed. Useful when failOnError is set to false and you want to handle the failure elsewhere in the build file.

Default is to not set any property.

schemaIdProperty No

The name of an ant property to set to the SchemaId associated with the generated schema. This is a string value that looks like "Schema_d462f3e631781b00ef812561115c48f6". These values are provided to @OnSchemaChange annotated methods.

Default is to not set any property.

classpath or classpathref Yes

Specifies the search path containing classes with @PermazenType annotations.

packages Yes, unless classes are specified

Specifies one or more Java package names (separated by commas and/or whitespace) under which to look for classes with @PermazenType annotations.

Use of this attribute requires Spring's classpath scanning classes (spring-context.jar); these must be on the <taskdef> classpath.

classes Yes, unless packages are specified

Specifies one or more Java class names (separated by commas and/or whitespace) of classes with @PermazenType annotations.

encodingRegistry No

Specifies the name of an optional custom EncodingRegistry class.

By default, a DefaultEncodingRegistry is used.

Classes are found by scanning the packages listed in the "packages" attribute. Alternatively, or in addition, specific classes may specified using the "classes" attribute.

To install this task into ant: 

  <project xmlns:permazen="urn:io.permazen.ant" ... >
      ...
      <taskdef uri="urn:io.permazen.ant" name="schema"
        classname="io.permazen.ant.SchemaGeneratorTask" classpathref="permazen.classpath"/>

Example of generating a schema XML file that corresponds to the specified Java model classes: 

  <permazen:schema mode="generate" classpathref="myclasses.classpath"
    file="schema.xml" packages="com.example.model"/>

Example of verifying that the schema generated from the Java model classes has not changed incompatibly (i.e., in a way that would require a new schema version): 

  <permazen:schema mode="verify" classpathref="myclasses.classpath"
    file="expected-schema.xml" packages="com.example.model"/>

Example of doing the same thing, and also verifying the generated schema is compatible with prior schema versions that may still be in use in production databases: 

  <permazen:schema mode="verify" classpathref="myclasses.classpath"
    file="expected-schema.xml" packages="com.example.model">
      <permazen:oldschemas dir="obsolete-schemas" includes="*.xml"/>
  </permazen:schema>
See Also:

  • Field Details

  • Constructor Details

    • SchemaGeneratorTask

      public SchemaGeneratorTask()

  • Method Details

    • setClasses

      public void setClasses(String classes)

    • setPackages

      public void setPackages(String packages)

    • setMode

      public void setMode(String mode)

    • setFailOnError

      public void setFailOnError(boolean failOnError)

    • setVerifiedProperty

      public void setVerifiedProperty(String verifiedProperty)

    • setSchemaIdProperty

      public void setSchemaIdProperty(String schemaIdProperty)

    • setFile

      public void setFile(File file)

    • createClasspath

      public org.apache.tools.ant.types.Path createClasspath()

    • setClasspath

      public void setClasspath(org.apache.tools.ant.types.Path classPath)

    • setClasspathRef

      public void setClasspathRef(org.apache.tools.ant.types.Reference ref)

    • setEncodingRegistryClass

      public void setEncodingRegistryClass(String encodingRegistryClassName)

    • addOldSchemas

      public void addOldSchemas(org.apache.tools.ant.types.FileSet oldSchemas)

    • execute

      public void execute()
      Overrides:
      execute in class org.apache.tools.ant.Task
      Throws:
      org.apache.tools.ant.BuildException - if operation fails