sculptor-generator.properties

[Pavel Tavoda]

Hello,

now when we moved all 'SpecialCases' to separate project src/main/resources/generator contains just one file 'scultpro-generator.properties' can we move it back to src/main/resources and remove generator directory? What do you think?

/Pavel

[Torsten Juergeleit]

Personally I'm not fond of mixing all the sculptor-related stuff (*.btdesign, sculptor*.properties, *.dot, *.png, *.html, *.css) with the project-related stuff (*.xml,*.properties, ...) usually placed in "src/main/resources/". We've to fiddle around with exclusion filters (like this one or this one) to keep this stuff from creeping into the final deployment units.

How about "hiding" the sculptor-related meta data by adopting the Maven way "META-INF/maven/" or Spring way "META-INF/spring/" by using the namespace "META-INF/sculptor/", e.g. "src/main/resources/META-INF/sculptor/model.btdesign" and "src/main/resources/META-INF/sculptor/generator.properties"?

And we should add more properties to the Sculptor Maven plugin and the generator templates to allow the user to customize the location of generated artifacts, e.g. the output folder of the generated UML documentation. Currently only the path to the root model file and the default output folders can by modified by the user.

/Torsten

[Pavel Tavoda]

Now I tested and it's working, we can move it to 'generator' project where SpecialCases resides.

You can change output of slots in sculptor-generator.properties:

# Output slots

# define output path and overwrite (default false) for output slots

outputSlot.path.TO_SRC=src/main/java

outputSlot.path.TO_RESOURCES=src/main/resources

outputSlot.path.TO_GEN_SRC=src/generated/java

outputSlot.path.TO_GEN_RESOURCES=src/generated/resources

outputSlot.path.TO_WEBROOT=src/main/webapp

outputSlot.path.TO_SRC_TEST=src/test/java

outputSlot.path.TO_RESOURCES_TEST=src/test/resources

outputSlot.path.TO_GEN_RESOURCES_TEST=src/test/generated/resources

outputSlot.path.TO_GEN_SRC_TEST=src/test/generated/java

Maybe we can introduce some new slot for documentation and according to this (http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) we can default it to src/site (src/generated/site?).

All *.btdesign is definitelly something we have to hide for packaging (src/main/scripts?). I don't like idea with META-INF, it's too deep for most important files.

[Torsten Juergeleit]

You can change output of slots in sculptor-generator.properties:

By using this configuration (only known to the generator implementation internally) the Sculptor Maven plugin doesn't know the changed output locations.
There's no guarantee that the clean-up and image generation are working properly. This mechanism was intended for unit-/integration-testing of the generator.

In the context of a Maven build the corresponding Sculptor Maven plugin properties should be used instead.

Maybe we can introduce some new slot for documentation and according to this (http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) we can default it to src/site (src/generated/site?).

Yes, this makes sense.

All *.btdesign is definitelly something we have to hide for packaging (src/main/scripts?). I don't like idea with META-INF, it's too deep for most important files.

Putting it in a separate resource folder of the Maven project will not hide the corresponding Sculptor meta data with the target build artifact. Without a name space (within the various resource folders) the Sculptor artifacts will be packaged in the root (JAR plugin) or "WEB-INF/classes/" (WAR plugin) of the final build artifact.

I'm only aware of a single use case where Sculptor meta data is need in a build artifact: In the case of  a Sculptor model which is spread accross in multiple JARs at least the imported "*.btdesign" have to included somewhere in the client JARs.

So how about this:

1. We place the Sculptor meta data in a separate folder (e.g. "src/main/sculptor/") which is not picked-up automatically by Mavens resource plugin.
2. In Sculptors Maven plugin we put this folder on the generators classpath (these artifacts are only used by Sculptors generator internally).
3. For packaging a Sculptor model client JAR (this is the only use case Sculptors meta data has to be available in a build target) Sculptor Maven plugin provides a new goal "package" (bound to Mavens package "phase") which puts folder as a resource (initialized with a sculptor-specific target path -> Java package, e.g. "META-INF/sculptor/") into the list of the projects resources. This way Mavens JAR plugin picks up Sculptors meta data and in places them in the aforementioned target path (Java package) configured in Sculptor Maven "package" goal.
   

/Torsten

[Pavel Tavoda]

On Thursday, September 19, 2013 6:25:24 PM UTC+2, Torsten Juergeleit wrote:

You can change output of slots in sculptor-generator.properties:

By using this configuration (only known to the generator implementation internally) the Sculptor Maven plugin doesn't know the changed output locations.
There's no guarantee that the clean-up and image generation are working properly. This mechanism was intended for unit-/integration-testing of the generator.

In the context of a Maven build the corresponding Sculptor Maven plugin properties should be used instead.

Can't you simply load sculptor-generator.properties (and default-sculptor-generator.properties) they are for sure on classpath of plugin? 

Maybe we can introduce some new slot for documentation and according to this (http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) we can default it to src/site (src/generated/site?).

Yes, this makes sense.

I will create new DOC slot and change doc templates to use it. Default will be 'src/site/generated'.

 

All *.btdesign is definitelly something we have to hide for packaging (src/main/scripts?). I don't like idea with META-INF, it's too deep for most important files.

Putting it in a separate resource folder of the Maven project will not hide the corresponding Sculptor meta data with the target build artifact. Without a name space (within the various resource folders) the Sculptor artifacts will be packaged in the root (JAR plugin) or "WEB-INF/classes/" (WAR plugin) of the final build artifact.

I'm only aware of a single use case where Sculptor meta data is need in a build artifact: In the case of  a Sculptor model which is spread accross in multiple JARs at least the imported "*.btdesign" have to included somewhere in the client JARs.

So how about this:

1. We place the Sculptor meta data in a separate folder (e.g. "src/main/sculptor/") which is not picked-up automatically by Mavens resource plugin.
2. In Sculptors Maven plugin we put this folder on the generators classpath (these artifacts are only used by Sculptors generator internally).
3. For packaging a Sculptor model client JAR (this is the only use case Sculptors meta data has to be available in a build target) Sculptor Maven plugin provides a new goal "package" (bound to Mavens package "phase") which puts folder as a resource (initialized with a sculptor-specific target path -> Java package, e.g. "META-INF/sculptor/") into the list of the projects resources. This way Mavens JAR plugin picks up Sculptors meta data and in places them in the aforementioned target path (Java package) configured in Sculptor Maven "package" goal.

It looks good, however can't we just put src/main/sculptor to 'resources' in pom.xml? Normaly when you have 'shared' project you want build it always with model files packaged.

Pavel

[Torsten Juergeleit]

In the context of a Maven build the corresponding Sculptor Maven plugin properties should be used instead.

 

Can't you simply load sculptor-generator.properties (and default-sculptor-generator.properties) they are for sure on classpath of plugin? 

I see your point (your hunting for KISS principle :-P). But there are times where simplicity is not sufficient :-)

The Maven world it's not so simple:

The Maven plugin itself doesn't use the Sculptor generator and its dependencies. The plugin only starts the generator as a black-box via the generators runtime main class. All the gory details of Sculptors generator with its Xtend magic, template overriding and overridden properties loader stuff is not available to the Maven plugin. 

So "loading sculptor-generator.properties" means copying stuff from the generator into the plugins pure-java/maven world. I don't think it's worth it.

And I didn't start talking about architectural stuff like loose coupling, separation of concerns, abstracting technical details...

I'm not keen on polluting the yet lean-'n-mean Maven plugin with too many generator-related internals. The current interface of setting a few system properties and calling a main method with some arguments seems appropriate to me.

I will create new DOC slot and change doc templates to use it. Default will be 'src/site/generated'.

Great. Please use a ticket for this enhancement.

It looks good, however can't we just put src/main/sculptor to 'resources' in pom.xml? Normaly when you have 'shared' project you want build it always with model files packaged.

You're going for the KISS principle again :-P) Ok, let's do a reality-check with the Maven world by using this resources-in-pom approach:

1. The configuration of the POM becomes clumsy, because 
• We've to repeat the default resource configuration because we're overriding the default resource configuration defined in the super POM.
  
• We've to define an include filter for "*.btdesign". The generator properties stuff has to be excluded from the client JAR to not being picked up the importing projects generator.
2. Early in the life cycle (in "process-resources" phase) the Maven resource plugin picks up the filtered stuff in "src/main/sculptor" and copies it to "target/classes". So all the model stuff in the Sculptor folder is accessible by the other plugins.
3. Later in the life cycle (in "package" phase) the jar plugin picks-up all the stuff from "target/classes/" (including our sculptor meta data). But wait: We only need this stuff for the client jar and not the main jar. 

Hhm, it seems that in both approaches (your resources-in-pom approach and my additional-package-plugin-goal approach) we have to define filters for both executions of the JAR plugin (main and client jar).

We should think about it :-)

/Torsten

[Pavel Tavoda]

On Thursday, September 19, 2013 11:31:35 PM UTC+2, Torsten Juergeleit wrote:

In the context of a Maven build the corresponding Sculptor Maven plugin properties should be used instead.

 

Can't you simply load sculptor-generator.properties (and default-sculptor-generator.properties) they are for sure on classpath of plugin? 

I see your point (your hunting for KISS principle :-P). But there are times where simplicity is not sufficient :-)

The Maven world it's not so simple:

The Maven plugin itself doesn't use the Sculptor generator and its dependencies. The plugin only starts the generator as a black-box via the generators runtime main class. All the gory details of Sculptors generator with its Xtend magic, template overriding and overridden properties loader stuff is not available to the Maven plugin. 

So "loading sculptor-generator.properties" means copying stuff from the generator into the plugins pure-java/maven world. I don't think it's worth it.

And I didn't start talking about architectural stuff like loose coupling, separation of concerns, abstracting technical details...

I'm not keen on polluting the yet lean-'n-mean Maven plugin with too many generator-related internals. The current interface of setting a few system properties and calling a main method with some arguments seems appropriate to me.

I understand your point but adding something like:

   Property.load(This.class.getResourceAsStream("sculptor-generator.properties"))

is not that much. You don't need any magic or generator internals. When is loaded than OK, override your defaults, it's about another 6 lines of code ;-). To make it more maven-ized, you can define property file name as another property.

 

I will create new DOC slot and change doc templates to use it. Default will be 'src/site/generated'.

Great. Please use a ticket for this enhancement.

OK #57

 

It looks good, however can't we just put src/main/sculptor to 'resources' in pom.xml? Normaly when you have 'shared' project you want build it always with model files packaged.

You're going for the KISS principle again :-P) Ok, let's do a reality-check with the Maven world by using this resources-in-pom approach:

1. The configuration of the POM becomes clumsy, because 
• We've to repeat the default resource configuration because we're overriding the default resource configuration defined in the super POM.
  
• We've to define an include filter for "*.btdesign". The generator properties stuff has to be excluded from the client JAR to not being picked up the importing projects generator.
2. Early in the life cycle (in "process-resources" phase) the Maven resource plugin picks up the filtered stuff in "src/main/sculptor" and copies it to "target/classes". So all the model stuff in the Sculptor folder is accessible by the other plugins.
3. Later in the life cycle (in "package" phase) the jar plugin picks-up all the stuff from "target/classes/" (including our sculptor meta data). But wait: We only need this stuff for the client jar and not the main jar. 

Hhm, it seems that in both approaches (your resources-in-pom approach and my additional-package-plugin-goal approach) we have to define filters for both executions of the JAR plugin (main and client jar).

We should think about it :-)

:-) I like your analytic approach

My idea was just put it inside pom in archetype into comment and than when needed just uncomment it.

/Pavel

[Torsten Juergeleit]

I understand your point but adding something like:

   Property.load(This.class.getResourceAsStream("sculptor-generator.properties"))

is not that much. You don't need any magic or generator internals. When is loaded than OK, override your defaults, it's about another 6 lines of code ;-). To make it more maven-ized, you can define property file name as another property.

Ok, in this case I would suggest to provide only a single place to let the user customize the output slots. Otherwise this leeds to confusion and unneccessary complexity. So let's remove the properties from the Maven plugin which are used to expose the output slots and use instead the generators code to retrieve the list of output slots used by the templates during code generation.

We could implement a new public static method "SculptorGeneratorRunner.getOutputSlots()" which use "PropertiesBase.getProperties("outputslot.path.", true)" internally. We have to do some classloader tricks to combine the Maven projects classpath (where the "sculptor-generator.properties" is located) with the generator libraries (where the "default-sculptor-generator.properties" is located). But should be doable.

At the end of the day the generator is reponsible to expose the list of output slots (which used internally by the templates) to the Maven plugin.

What do you think?

Hhm, it seems that in both approaches (your resources-in-pom approach and my additional-package-plugin-goal approach) we have to define filters for both executions of the JAR plugin (main and client jar).

We should think about it :-)

:-) I like your analytic approach

My idea was just put it inside pom in archetype into comment and than when needed just uncomment it.

Ok, how about this:

By using the " additional-package-plugin-goal" approach with a name space (e.g. "META-INF/sculptor/") for the "*.btdesign" artifacts we can live with the fact that the (unfiltered) main jar and the client contain both the identical "*.btdesign" artifacts. If one doesn't like the sculptor models being packaged with the main jar can add a simple exclusion filter of "/META-INF/sculptor/*" to the JAR plugin execution config for the main jar.

I don't see a chance to get the Sculptor artifacts from being packaged to the main jar without using a filter. At the end of the day we need the artifacts in the client jar.

/Torsten

[Pavel Tavoda]

On Friday, September 20, 2013 12:26:06 PM UTC+2, Torsten Juergeleit wrote:

I understand your point but adding something like:

   Property.load(This.class.getResourceAsStream("sculptor-generator.properties"))

is not that much. You don't need any magic or generator internals. When is loaded than OK, override your defaults, it's about another 6 lines of code ;-). To make it more maven-ized, you can define property file name as another property.

Ok, in this case I would suggest to provide only a single place to let the user customize the output slots. Otherwise this leeds to confusion and unneccessary complexity. So let's remove the properties from the Maven plugin which are used to expose the output slots and use instead the generators code to retrieve the list of output slots used by the templates during code generation.

We could implement a new public static method "SculptorGeneratorRunner.getOutputSlots()" which use "PropertiesBase.getProperties("outputslot.path.", true)" internally. We have to do some classloader tricks to combine the Maven projects classpath (where the "sculptor-generator.properties" is located) with the generator libraries (where the "default-sculptor-generator.properties" is located). But should be doable.

At the end of the day the generator is reponsible to expose the list of output slots (which used internally by the templates) to the Maven plugin.

What do you think?

I'm not sure now, I will have to check but properties are lazy loaded after generation is started. You can't obtain values before generation but we can change this behavior. Why you don't like idea of loading properties file directly, is here some classpath issue? Properties are defined on one place but read from two different places, that is not violation of anything.

 

Hhm, it seems that in both approaches (your resources-in-pom approach and my additional-package-plugin-goal approach) we have to define filters for both executions of the JAR plugin (main and client jar).

We should think about it :-)

:-) I like your analytic approach

My idea was just put it inside pom in archetype into comment and than when needed just uncomment it.

Ok, how about this:

By using the " additional-package-plugin-goal" approach with a name space (e.g. "META-INF/sculptor/") for the "*.btdesign" artifacts we can live with the fact that the (unfiltered) main jar and the client contain both the identical "*.btdesign" artifacts. If one doesn't like the sculptor models being packaged with the main jar can add a simple exclusion filter of "/META-INF/sculptor/*" to the JAR plugin execution config for the main jar.

I don't see a chance to get the Sculptor artifacts from being packaged to the main jar without using a filter. At the end of the day we need the artifacts in the client jar.

Yes, that is simplest way.

[Torsten Juergeleit]

I'm not sure now, I will have to check but properties are lazy loaded after generation is started. You can't obtain values before generation but we can change this behavior.

At first glance calling PropertiesBase.getProperties("outputslot.path.", true) with a properly initialized ThreadContextClass loader looks good. Ok, the methods package visibility has to be changed and the lazily loading would kicking-in multiple time. But hey, in comparision to other stuff that's piece of cake :-)

Why you don't like idea of loading properties file directly, is here some classpath issue? Properties are defined on one place but read from two different places, that is not violation of anything.

I'm not fond on this "using something despite not being responsible for it but due to knowlegde about the inner workings being able to fiddle around with it anyway" approach. IMHO here are architectural principles (separation of concerns, loose coupling, abstraction) over-ruling KISS :-P

And the classloader issues have to be handled anyway, e.g. GeneratorMojo.extendPluginClasspath().

/Torsten