Sculptor


Overview

Sculptor comes with its own Maven plugin with the Maven coordinates org.sculptorgenerator:sculptor-maven-plugin. This plugin has the following responsibilities:

The plugin provides the following features:

  • The plugin keeps track of all artifacts created during code generation. This information is used to delete the generated artifacts when the code generator is executed again or when the Maven clean plugin is executed.
  • To skip unneccessary Sculptor generator executions the plugin checks if one of the generator-related files (e.g. pom.xml, Sculptor models or generator configuration) is modified.
  • The plugin registers itself with the Eclipse m2e plugin (Eclipse Maven support) to provide the following information:
    • metadata for the Sculptor Mven plugins Maven lifecycle mapping
    • directories of the Maven project which should be used as classpath entries within an Eclipse project
  • The plugin maintains its own classpath which is independent from the projects classpath.

Usage

To activate the Sculptor Maven plugin within a maven project the following has to be added to the projects POM:

<build>
	<plugins>
		<plugin>
			<groupId>org.sculptorgenerator</groupId>
			<artifactId>sculptor-maven-plugin</artifactId>
			<version>${sculptor.version}</version>
			<executions>
				<execution>
					<id>cleanup</id>
					<goals>
						<goal>clean</goal>
					</goals>
				</execution>
				<execution>
					<id>code-generation</id>
					<goals>
						<goal>generate</goal>
					</goals>
				</execution>
				<execution>
					<id>image-generation</id>
					<goals>
						<goal>generate-images</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

This registers the Sculptor plugins goals (with their default lifecyle phase) to the Maven projects lifecycle:

  • For mvn clean the plugins clean goal is executed to delete all artifacts created during the last code generation.
  • For mvn generate-sources (or any phase later) the plugins generate goal is executed to run Sculptors code generator.
  • For mvn generate-resources (or any phase later) the plugins generate-images goal is executed to use the dot command for generating images from the .dot files created during the last code generation.

The details of this plugin reference can be reduced by defining the Sculptor plugin in the <pluginManagement> section of a parent POM, e.g.

<build>
	<pluginManagement>
		<plugins>
			<plugin>
				<groupId>org.sculptorgenerator</groupId>
				<artifactId>sculptor-maven-plugin</artifactId>
				<version>${sculptor.version}</version>
				<executions>
					<execution>
						<id>cleanup</id>
						<goals>
							<goal>clean</goal>
						</goals>
					</execution>
					<execution>
						<id>code-generation</id>
						<goals>
							<goal>generate</goal>
						</goals>
					</execution>
					<execution>
						<id>image-generation</id>
						<goals>
							<goal>generate-images</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</pluginManagement>
</build>

To activate the plugin (which is defined this way) only the following has to be added to the projects POM:

<build>
	<plugins>
		<plugin>
			<groupId>org.sculptorgenerator</groupId>
			<artifactId>sculptor-maven-plugin</artifactId>
		</plugin>
	</plugins>
</build>

The plugin keeps track of the artifacts created by the Sculptor generator. This information is used to delete the generated artifacts when the Sculptor generator is executed again or when the Maven clean plugin is executed. The corresponding information is retrieved from the hidden file .sculptor-status. This file is deleted when mvn clean is executed.

Some important notices:

  • DO NOT put the file .sculptor-status under version control. It’s not tragical mistake but you will have many problems with merging this file when updating. Plugin works nice without this. (For git add this files to .gitignore)

  • DO NOT put all files under version control. Only modified files should go to version control system (files from src/generated should never go into version control system).

Configuration

The Sculptor Maven plugin goals provide the following configuration properties with reasonable defaults (conventon over configuration):

Property Default Goals Purpose
checkFileSets src/main/resources/*.btdesign generate List of Maven FileSets that will be checked on up-to-date. If all resources are up-to-date the plugin stops the execution, because there are no files to regenerate. The entries of this list can be relative path to the project root or absolute path.
clean true generate Delete all previously generated files before starting code generation (can be set from command line using -Dsculptor.generator.clean=false)
command dot generate-images Command to execute to generate the images.
Don’t include any command line arguments, e.g.image format or input files. These are handled by the mojo.
force false generate Don’t try to detect if Sculptor code generation is up-to-date and can be skipped (can be set from command line using -Dsculptor.generator.force=true)
model src/main/resources/model.btdesign generate Relative path of the Sculptor model source file
outletDocDir src/site generate Directory for test non-source-code artifacts. Existings artifacts will be overwritten.
outletResDir src/generated/resources generate Directory for non-source-code artifacts. Existings artifacts will be overwritten.
outletResOnceDir src/main/resources generate Directory for non-source-code artifacts. If an artifact with the same name already exists, the generation of the artifact will be skipped (one-shot).
outletResTestDir src/test/generated/resources generate Directory for test non-source-code artifacts. Existings artifacts will be overwritten.
outletResTestOnceDir src/test/resources generate Directory for test non-source-code artifacts. If an artifact with the same name already exists, the generation of the artifact will be skipped (one-shot).
outletSrcDir src/generated/java generate Directory for source-code artifacts. Existings artifacts will be overwritten.
outletSrcOnceDir src/main/java generate Directory for source-code artifacts. If an artifact with the same name already exists, the generation of the artifact will be skipped (one-shot).
outletSrcTestDir src/test/generated/java generate Directory for test source-code artifacts. Existings artifacts will be overwritten.
outletSrcTestOnceDir src/test/java generate Directory for test source-code artifacts. If an artifact with the same name already exists, the generation of the artifact will be skipped. (one-shot).
outletWebrootDir src/main/webapp generate Directory for Webapp artifacts. If an artifact with the same name already exists, the generation of the artifact will be skipped (one-shot).
properties   generate Properties (key is the XML tag and value is the XML tags body) used to define system properties (like sculptor.generatorPropertiesLocation) or to overrride the settings retrieved from default-sculptor-generator.properties
skip false clean Skip the clean-up of previously generated files (can be set from command line using -Dsculptor.clean.skip=true)
skip false generate Skip the execution of the code generator (can be set from command line using -Dsculptor.generator.skip=true)
skip false generate-images Skip the execution of the image generator (can be set from command line using -Dsculptor.graphviz.skip=true)
statusFile .sculptor-status clean, generate, generate-images File holding the status of the last code generator execution.
verbose false clean, generate, generate-images Activates verbose logging of the plugin (can be set from command line using -Dverbose=true). Activating debug logging of Sculptors generator library is decribed in the section Logging.

These properties are used within the <configuration> tag in the Sculptor Maven plugin definition, e.g.

<plugin>
	<groupId>org.sculptorgenerator</groupId>
	<artifactId>sculptor-maven-plugin</artifactId>
	<executions>
		<execution>
			<id>code-generation</id>
			<goals>
				<goal>generate</goal>
			</goals>
			<configuration>
				<verbose>true</verbose>
				<checkFilesets>
					<checkFileset>
						<directory>${basedir}</directory>
						<includes>
							<include>src/**</include>
						</includes>
						<excludes>
							<exclude>**/.gitignore</exclude>
						</excludes>
					</checkFileset>
				</checkFilesets>
				<properties>
					<sculptor.generatorPropertiesLocation>
						${basedir}/src/sculptor/generator.properties
					</sculptor.generatorPropertiesLocation>
				</propperties>
			</configuration>
		</execution>
	</executions>
</plugin>

Some of these properties can be added to the commandline as system properties, e.g.

mvn clean test -Dverbose=true -Dsculptor.graphviz.skip=true

Classpath

The plugin uses its own classloader which is separated from the current Maven projects one.

To add additional dependencies to the the plugins classpath (e.g. for cross-project references) add these dependencies in the plugins/plugin section of the project pom.xml:

<plugin>
	<groupId>org.sculptorgenerator</groupId>
	<artifactId>sculptor-maven-plugin</artifactId>
	<executions>
		<execution>
			<id>code-generation</id>
			<goals>
				<goal>generate</goal>
			</goals>
		</execution>
		<dependencies>
			<dependency>
				<groupId>org.foo.common</groupId>
				<artifactId>foo-common</artifactId>
				<version>1.0</version>
				<classifier>client</classifier>
			</dependency>
		</dependencies>
	</executions>
</plugin>

Logging

Sculptor uses the SLF4J logging abstraction which supports various logging frameworks (e.g. java.util.logging, logback, log4j).

Maven 3.1 and newer

Starting with version 3.1 Maven ships with the SLF4J Simple Logger. So adding the Java system property -Dorg.slf4j.simpleLogger.log.org.sculptor=debug to the Maven command line activates the debug logging of Sculptors generator library:

mvn clean generate-sources -Dorg.slf4j.simpleLogger.log.org.sculptor=debug

Maven 3.0

With Maven 3.0 Sculptor uses the Logback logging framework. So adding the Java system property -Dlogback.configurationFile=</path/to/logback.xml> to the Maven command line activates debug logging of Sculptors generator library. The corresponding logback.xml defines a logger with the name “org.sculptor”:

<?xml version="1.0" encoding="UTF-8"?>
<configuration> 
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> 
    <encoder> 
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> 
    </encoder> 
  </appender>  

  <logger name="org.sculptor" level="DEBUG"/>

  <root level="WARN">
    <appender-ref ref="STDOUT"/> 
  </root> 
</configuration>
Fork me on GitHub