Re: [Jamon-hackers] Support for jamon.properties from the classpath

[Ian R. <ian...@gm...>]

(adding jamon-hackers back to the recipient list; it looks like I
accidentally did a reply instead of reply-all several messages back)

You asked how much value there is in offering a default set of
jamon.properties. At this point, we have feature requests for:

   - aliases (https://sourceforge.net/p/jamon/feature-requests/7/)
   - defaultEncoding (https://sourceforge.net/p/jamon/feature-requests/8/)
   (this is not currently a jamon property, but probably should be)
   - contextType (same as defaultEncoding)

The only property not currently requested is emitMode, but it doesn't to me
seem unreasonable that one might want to have a default setting for that as
well.

The next question is whether it would be appropriate to set these via a
jar. contextType is the clearest use case for this, since if you depend on
a jar with templates expecting a certain context site, you likely need to
use the same one (or a subtype). As for the others, while the jar isn't
necessarily a "natural" choice, it doesn't feel like an "unnatural" choice
either, nor does it seem completely out of step with the java ecosystem: an
annotation processor on the classpath can impact compilation of source
files, including generation of errors.

The big issue I have with the other options that have been put forth is
that I'm not seeing any easy way to set up a standard configuration that
can be easily applied to a project without copy-and-pasting the whole
configuration. But while copy-and-paste is O(n) in the number of
properties, adding a jar is O(1). Worse, to solve this requires a solution
for each build tool we have (currently 4).

You do have a good point about a property value changing out from
underneath you. It would likely be problematic if aliases or
defaultEncoding were to change. To remedy this, template library
maintainers would need to understand that changing existing aliases or the
defaultEncoding in jamon.lib.properties would constitute a backwards
incompatible change. This would be similar to a library maintainer changing
the name of an enum value or method name.

For contextType, it is arguably a good thing that a referenced template
library could change it - if my dependency changes its context type, and I
don't, my build should fail. Setting emitMode as standard policy doesn't
feel like a bad thing; indeed, if an architect decides that it needs to be
tightened up, having it automatically propagate to a number of projects
could be a good thing - it might break the build, but in ways that one
would want it to break.

  - Ian





On Fri, Aug 30, 2013 at 9:16 AM, Jay Sachs <ja...@co...> wrote:

> If we determine that a default set of jamon.properties is useful, I would
> advocate pulling them unambiguously from system properties, e.g.
>
> org.jamon.defaultEncoding=
> org.jamon.defautJamonContext=
> org.jamon.defaultAlias.abc=
> org.jamon.defaultAlias.def=
> org.jamon.defaultAlias.xyz=
>
>
>
>
> On Thu, Aug 29, 2013 at 9:59 AM, Jay Sachs <ja...@co...> wrote:
>
>> I need to back up a minute. The stuff specified in jamon.properties only
>> is applicable to source templates; it's irrelevant in a precompiled
>> template library. Specifying a default encoding in jamon.properties I think
>> we agree is a Good Thing. The question you and I are discussing is: what is
>> the value of offering a "default" set of jamon.properties, and if it's
>> valuable, how should it be specified?
>>
>> Personally, I think the value is pretty low. Whether on a
>> per-template-project basis you need to specify some pom elements or copy
>> your standard jamon.properties in, I think either one is fine. Consider the
>> following: I'm using some classpath-provided jamon.properties (that I get
>> from a specific dependency, say). I write my templates. Now, my dependency
>> changes one or more of the properties. I can think of nothing good
>> happening in general (though I can imagine some alias-changing to achieve a
>> versioning might work, but that should be done via a new template library
>> dependency version, not re-pointing aliases).
>>
>> What's a good use case for not-source-provided jamon.properties?
>>
>>
>> On Thu, Aug 29, 2013 at 9:32 AM, Ian Robertson <ian...@gm...
>> > wrote:
>>
>>> If it's just setting the encoding, then I would agree with you - its
>>> just as easy to specify a property in the build as it is to include a jar.
>>> However, the challenge is when there are a number of properties that one
>>> wishes set in a consistent fashion. For example, at Overstock, they make
>>> significant use of org.jamon.alias.*alaisName* properties, and they
>>> also use jamonContext. If one has a parent pom, then I believe the jamon
>>> configuration can be set to be inherited, but there is to my knowledge no
>>> easy way to share a default configuration in maven between projects not
>>> sharing a common parent pom. Similarly, sharing properties between eclipse
>>> projects is not an easy thing to do.
>>>
>>> I share your concern about the jamon.properties file of a project being
>>> accidentally included in the jar, leading to unnecessary conflicts. There
>>> are a couple of ways we could mitigate this. One would be to use a
>>> different name for properties resources, say jamon.lib.properties. Another
>>> would be a way to specify on a property-by-property basis whether the
>>> property was inheritable; this would likely require supporting a new syntax
>>> - XML seems like a reasonable choice.
>>>
>>> My other concern about a per-tool configuration is that we already have
>>> four tools to support - eclipse, maven, ant and command line. It seems
>>> reasonable that a gradle plugin would be in order as well. I'd much prefer
>>> that we use a solution which is already supported by these tools, rather
>>> than create a new one that needs to be maintained separately in each of
>>> them.
>>>
>>>
>>> On Mon, Aug 26, 2013 at 2:57 PM, Jay Sachs <ja...@co...> wrote:
>>>
>>>> Consider the use case of splitting templates into library "chunks".
>>>> Each library chunk will have a jamon.properties file specifying the default
>>>> encoding. You'll have to be careful not to include those in the built jars,
>>>> or else it ends up ambiguous. And note that for library templates, we don't
>>>> *care* what the encoding *was* of the source template. It's already been
>>>> compiled.
>>>>
>>>> I really think a setting in pom.xml and/or .eclipse/project and/or
>>>> cmdline flag to tool is the way to go here.
>>>>
>>>>
>>>> On Mon, Aug 26, 2013 at 2:45 PM, Ian Robertson <
>>>> ian...@gm...> wrote:
>>>>
>>>>> It appears that currently, the maven plugin creates a classloader from
>>>>> the testclasspath (this is almost certainly wrong - at the very least, only
>>>>> TestJamonMojo should do this, while JamonMojo should use the compile
>>>>> classpath), and passes this to the constructor of JamonProcessor, which
>>>>> passes it via TemplateParserImpl to the constructor of TemplateDescriber.
>>>>> TemplateDescriber currently uses this classloader in its
>>>>> computeTemplateDescription method to look for library templates.
>>>>>
>>>>> The ant task allows specifying the classpath to be used for the
>>>>> classloader. Currently, the commandline tool simply passes its own
>>>>> classloader as the classloader.
>>>>>
>>>>> There is arguably room for improvement with how we let people
>>>>> configure this. However, since we already need to support template
>>>>> libraries, why not use the same mechanism to support a property "library"?
>>>>>
>>>>>
>>>>> On Mon, Aug 26, 2013 at 10:27 AM, Jay Sachs <ja...@co...> wrote:
>>>>>
>>>>>> And that classloader gets configured ... where? pom.xml? eclipse
>>>>>> plugin properties? At that point, you might as well inline the properties
>>>>>> into the build system configuration file (pom element, eclipse project
>>>>>> preference pane, etc).
>>>>>>
>>>>>>
>>>>>> On Mon, Aug 26, 2013 at 12:20 PM, Ian Robertson <
>>>>>> ian...@gm...> wrote:
>>>>>>
>>>>>>> I agree that we shouldn't use the classlaoder responsible for
>>>>>>> loading the jamon processor. But we pass a classloader to jamonprocessor so
>>>>>>> that it can introspect library templates. We could use that same
>>>>>>> classloader for jamon.properties.
>>>>>>>
>>>>>>> (On a related note, I can't find anything in our docs that states
>>>>>>> this, but it is in the code. Probably also ought to fix that...)
>>>>>>>
>>>>>>>
>>>>>>> On Mon, Aug 26, 2013 at 10:17 AM, Jay Sachs <ja...@co...>wrote:
>>>>>>>
>>>>>>>> The problem with the classpath that I see is that it's the
>>>>>>>> classpath run at template translation compilation time, not at java
>>>>>>>> compilation or runtime. I don't think it's a good idea to try and muck with
>>>>>>>> the classpath used to run the maven plugin.
>>>>>>>>
>>>>>>>>
>>>>>>>> On Mon, Aug 26, 2013 at 11:59 AM, Ian Robertson <
>>>>>>>> ian...@gm...> wrote:
>>>>>>>>
>>>>>>>>> URLs seem suboptimal to me. They work fine for an aggregator
>>>>>>>>> project, assuming that the user checks out that project, but otherwise,
>>>>>>>>> they won't help. Absolute URLs would require setting up a server to serve
>>>>>>>>> them (or choosing a canonical directory on every user's box).
>>>>>>>>>
>>>>>>>>> It would seem the classpath to use would be the same one we use
>>>>>>>>> for any library templates. Since we are already using this for templates,
>>>>>>>>> using it for jamon.properties seems natural to me.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Mon, Aug 26, 2013 at 8:11 AM, Jay Sachs <ja...@co...>wrote:
>>>>>>>>>
>>>>>>>>>> First: I'm coming around to the idea of an "externally" specified
>>>>>>>>>> default jamon.properties.
>>>>>>>>>>
>>>>>>>>>> The classpath idea is nice in that it is already implemented.
>>>>>>>>>> However, whose classpath is it? Don't we really mean "which ClassLoader(s)
>>>>>>>>>> to consult"?
>>>>>>>>>>
>>>>>>>>>> What about something more explicit and inherently unambiguous?
>>>>>>>>>> For instance, a URL argument to the processor which specifies the location
>>>>>>>>>> of the default jamon.properties? An absolute URL is easy; a relative URL
>>>>>>>>>> would be relative to something based on the build system -- in Maven, the
>>>>>>>>>> project root dir, in Eclipse, the Eclipse workspace root?
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> On Mon, Aug 26, 2013 at 10:00 AM, Ian Robertson <
>>>>>>>>>> ian...@gm...> wrote:
>>>>>>>>>>
>>>>>>>>>>> It would be nice if jamon could also pick up jamon.properties
>>>>>>>>>>> from the classpath. I know of at least two use cases:
>>>>>>>>>>>
>>>>>>>>>>> 1) electrotype's desire for a default encoding for all projects
>>>>>>>>>>> could be satisfied more elegantly this way
>>>>>>>>>>> 2) When a project using templates is broken up into multiple
>>>>>>>>>>> modules (maven sub projects), it would be nice to not have to copy the
>>>>>>>>>>> jamon.properties to each module. Overstock has this issue.
>>>>>>>>>>>
>>>>>>>>>>> The challenges I can see are:
>>>>>>>>>>> 1) how to merge a classpath jamon.properties with a source dir
>>>>>>>>>>> jamon.properties
>>>>>>>>>>> 2) how to handle multiple instances of jamon.properties on the
>>>>>>>>>>> classpath.
>>>>>>>>>>>
>>>>>>>>>>> To address these, I would propose the following resolution
>>>>>>>>>>> algorithm:
>>>>>>>>>>>
>>>>>>>>>>> When determining the value of property X for a given directory:
>>>>>>>>>>>
>>>>>>>>>>> 1) If there is a source-folder jamon.properties, and it
>>>>>>>>>>> specifies a value for X for the given directoy or any of it's parents, use
>>>>>>>>>>> the value of the fullest matching path. This is as we currently do things.
>>>>>>>>>>> 2) If there is not a value specified in the source-folder
>>>>>>>>>>> jamon.properties, or if no source-folder jamon.properties exists, look on
>>>>>>>>>>> the classpath for all jamon.properties resources.
>>>>>>>>>>> 2a) If none of these specify a value for X for the given
>>>>>>>>>>> directory or any of its parents, then X has no value.
>>>>>>>>>>> 2b) If exactly one of these specifies a value for X for the
>>>>>>>>>>> given directory or any of it's parents, use that value.
>>>>>>>>>>> 2c) If more than one jamon.properties resource specifies a value
>>>>>>>>>>> for X that could apply to the given directory, and the specified values are
>>>>>>>>>>> not all the same, (and again, there is no applicable value for X specified
>>>>>>>>>>> in the source-folder jamon.properties), throw an exception.
>>>>>>>>>>> 2d) conflicts for directories which have no .jamon files should
>>>>>>>>>>> not cause an exception
>>>>>>>>>>>
>>>>>>>>>>> The idea is that in general, a project should have no more than
>>>>>>>>>>> one jamon.properties on the classpath. If there are, its OK, as long as
>>>>>>>>>>> they don't conflict. If they do, then the project must resolve the
>>>>>>>>>>> ambiguity with a source-folder jamon.properties.
>>>>>>>>>>>
>>>>>>>>>>> One possible change would be to only consider it a conflict
>>>>>>>>>>> between multiple jamon.properties resources if there is not winner based on
>>>>>>>>>>> the most-specific path match. However, it seems right to allow the source
>>>>>>>>>>> jamon.properties to always have precedence regardless, even if it specifies
>>>>>>>>>>> a value at the root directory. Allowing classpath jamon.properties to
>>>>>>>>>>> compete on the basis of path-specificity would seem inconsistent.
>>>>>>>>>>>
>>>>>>>>>>> One risk I can see with this is if a build system is currently
>>>>>>>>>>> accidentally including jamon.properties in the jar (this could happen if
>>>>>>>>>>> src/main/java is also being used for jamon.properties). Builds would need
>>>>>>>>>>> to be modified to exclude these from the jar unless otherwise requested.
>>>>>>>>>>> Previously created jars could create a backwards incompatibility. I suspect
>>>>>>>>>>> that this risk is a manageable one, especially since projects that would be
>>>>>>>>>>> impacted by this are likely to also benefit from this feature.
>>>>>>>>>>>
>>>>>>>>>>> Thoughts?
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> ------------------------------------------------------------------------------
>>>>>>>>>>> Introducing Performance Central, a new site from SourceForge and
>>>>>>>>>>> AppDynamics. Performance Central is your source for news,
>>>>>>>>>>> insights,
>>>>>>>>>>> analysis and resources for efficient Application Performance
>>>>>>>>>>> Management.
>>>>>>>>>>> Visit us today!
>>>>>>>>>>>
>>>>>>>>>>> http://pubads.g.doubleclick.net/gampad/clk?id=48897511&iu=/4140/ostg.clktrk
>>>>>>>>>>> _______________________________________________
>>>>>>>>>>> Jamon-hackers mailing list
>>>>>>>>>>> Jam...@li...
>>>>>>>>>>> https://lists.sourceforge.net/lists/listinfo/jamon-hackers
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>