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 and @JFieldType 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.

The following attributes are supported by this task:

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.
matchNames	No	Whether to verify not only "same version" schema compatibility but also that the two schemas are actually identical, i.e., the same names are used for object types, fields, and composite indexes, and non-structural attributes such as delete cascades have not changed. Two schemas that are equivalent except for names are compatible, because the core API uses storage ID's, not names. However, if names change then some Permazen layer operations, such as index queries and reference path inversion, may need to be updated. Default is true. Ignored unless mode is 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.
schemaVersionProperty	No	The name of an ant property to set to the auto-generated schema version number. This is the schema version number that will be auto-generated when a schema version number of -1 is configured. This auto-generated version number is based on hashing the generated schema. Default is to not set any property.
classpath or classpathref	Yes	Specifies the search path containing classes with @PermazenType and @JFieldType 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 or @JFieldType 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 or @JFieldType annotations.
storageIdGeneratorClass	No	Specifies the name of an optional custom StorageIdGenerator class. By default, a DefaultStorageIdGenerator 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:

Permazen, SchemaModel

Field Summary

Fields

Modifier and Type	Field and Description
static String	MODE_GENERATE
static String	MODE_GENERATE_AND_VERIFY
static String	MODE_VERIFY

Fields inherited from class org.apache.tools.ant.Task

target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

description, location, project

Constructor Summary

Constructors

Constructor and Description
SchemaGeneratorTask()

Method Summary

Modifier and Type	Method and Description
void	addOldSchemas(org.apache.tools.ant.types.FileSet oldSchemas)
org.apache.tools.ant.types.Path	createClasspath()
void	execute()
void	setClasses(String classes)
void	setClasspath(org.apache.tools.ant.types.Path classPath)
void	setClasspathRef(org.apache.tools.ant.types.Reference ref)
void	setFailOnError(boolean failOnError)
void	setFile(File file)
void	setMatchNames(boolean matchNames)
void	setMode(String mode)
void	setPackages(String packages)
void	setSchemaVersionProperty(String schemaVersionProperty)
void	setStorageIdGeneratorClass(String storageIdGeneratorClassName)
void	setVerifiedProperty(String verifiedProperty)

Methods inherited from class org.apache.tools.ant.Task

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MODE_VERIFY

public static final String MODE_VERIFY

See Also:

Constant Field Values

MODE_GENERATE

public static final String MODE_GENERATE

See Also:

Constant Field Values

MODE_GENERATE_AND_VERIFY

public static final String MODE_GENERATE_AND_VERIFY

See Also:

Constant Field Values

Constructor Detail

SchemaGeneratorTask

public SchemaGeneratorTask()

Method Detail

setClasses

public void setClasses(String classes)

setPackages

public void setPackages(String packages)

setMode

public void setMode(String mode)

setMatchNames

public void setMatchNames(boolean matchNames)

setFailOnError

public void setFailOnError(boolean failOnError)

setVerifiedProperty

public void setVerifiedProperty(String verifiedProperty)

setSchemaVersionProperty

public void setSchemaVersionProperty(String schemaVersionProperty)

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)

setStorageIdGeneratorClass

public void setStorageIdGeneratorClass(String storageIdGeneratorClassName)

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