You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lenya.apache.org by Andreas Hartmann <an...@apache.org> on 2006/01/04 09:27:11 UTC

Re: RFC: suggestions for a ConfigurableInstantiator (1.4 document templating)

Joern Nettingsmeier wrote:
> Andreas Hartmann wrote:
> 
>>Joern Nettingsmeier wrote:
>>
>>>Andreas Hartmann wrote:
>>>
>>>
> 
> <snip>
> 
>>>but all i'm suggesting is to provide a hook to control the behaviour of
>>>the ConfigurableInstantiator. in the default case, the configuration
>>>file boils down to a simple list of files, which is what you originally
>>>suggested.
>>
>>I guess I see your point, and my comments where indeed of quite general
>>nature. But when I see script-like XML, all my alarm bells start ringing :)
> 
> 
> and for a reason. the thing is: i tried to be constructive, i can't find
> my way around the java code (yet), so i cobbled together something from
> the stuff i'm good at. i could not care less if there's xsl in the
> config file, but i do want all this to be configurable without having to
> touch java.

It's always a tightrope walk when to require using Java and when to
provide configuration options ... When I started working with Lenya,
I had the same feelings. The major reason for introducing Ant tasks was
to simplify the implementation of custom functionality. But unfortunately
this decision proved wrong because we lost powerful concepts like
polymorphism, exceptions, transactions, etc.

Sure, here we're talking about something different, I just wanted to
state why I'm hesitant when it comes to complex configuration options.
If the reason for the configuration options is that the API required
for implementation is too complex and too hard to understand, than
I'd prefer to simplify and clean up the API.


> my idea was that the xsl file would be parsed by the instantiator
> anyway, not just by an external xalan process - i was not suggesting to
> circumvent the java "business logic" at all. ultimate control of what
> happens to the new publication should remain with the instantiator.

>>At a first glance, the mechanism described in your mail could as well
>>be implemented using Ant with the XConfToolTask. But, the longer I think
>>about it, I'm rather concerned about the fact that files are copied and
>>patched at all. I tried to take care of this in the repo layer re-design,
>>whereas it's not yet finished.
>>
>>IMO
>>
>>
>>>  <file mode="copy" src="publication.xml">
>>>    <xsl:template match="lenya:name">
>>>      <lenya:name><xsl:value-of select="$pub_name"/></lenya:name>
>>>    </xsl:template>
>>>...
>>
>>should instead be
>>
>>  publication.setName(...);
>>  publication.setDescription(...);
> 
> 
> that is convincing.
> 
> but it should be configurable in an xml file, not hardcoded in java.
> do you agree?

Do you mean the fact that the publication's name and description are set?
IMO this is generic enough to implement it as the default behaviour.
If you want to change it - why not override the Java class? That's
done in a few minutes, if the base class is designed for inheritance
(small methods, template methods etc.)


> so ++votes for clean access to publication properties via the java api
> exclusively, but please please give me a config file to control it.

I'm still not quite sure - what would the config file contain?


>>The same should apply to policies etc. The access controller should be
>>configurable using the API and create configuration files whenever it
>>considers this appropriate. If Lenya supports instanciation of
>>publications during run-time, it should also allow this without copying
>>and patching any configuration files.
> 
> 
> agreed.
> 
> i guess the main difference is that, being new to lenya and java
> servlets, i'm working from the configuration files downwards, and you
> start from your java IDE upwards, so naturally our opinions about what
> is easiest and most elegant would differ ;)

Like so often, it's about people and not about the code :)


>>>i think the inheritance behaviour of a template is a property of this
>>>template and should thus be reflected in one of its configuration files.
>>>
>>>in unix speak, it's *policy* and should not be in the kernel (or the
>>>business logic in this case) IMHO. the kernel provides *mechanism*.
>>
>>I prefer thinking in terms of separate modules which communicate through
>>well-defined interfaces, not configuration files. But maybe I don't
>>understand you correctly.
> 
> 
> imho the servlet should provide all necessary functions (the
> "mechanism"), but it should not second-guess the user's needs and
> implement one particular behaviour ("policy").
> the instantiator needs to be so general that most lenya users never need
> to touch it. all its power must be accessible through the config file.

Hmmm, I don't share this opinion. We followed this strategy for a long
time, and it caused a lot of problems.

It doesn't seem to be possible to provide a component which is so "general
that most Lenya users never need to touch it". It is tempting to try it,
but there *will* be people who want something else. And the more flexible
the component is, the more complex becomes the configuration.

IMO the way to go is:

- provide a clean and well-documented API which supports all reasonable
   scenarios (of course this is subjective)

- add one or two samples and a tutorial

- the user implements the instantiator, either from scratch or by
   overriding an existing one

This way, you're not limited to the configuration options of a generic
instantiator. You can use all features provided by the Lenya core and modules.
I don't object that a configurable instantiator is a good thing to have,
but it shouldn't be too complex. Simple things should be simple
(configuration), complex things should be possible (Java).


> and to become really usable, instantiation needs those features i
> described in my initial post, namely a detailed description of which
> properties should be copied from the template and which ones referenced,
> and if copied, which alterations must be made.
> 
> <snip>
> 
>>>the instantiation of a publication is by nature a direct manipulation of
>>>its configuration.
>>
>>Yes, it is a manipulation of the configuration, but it should happen
>>only using well-defined interfaces. publication.xconf and publication.xml
>>are implementation details, although the documentation advises to
>>manipulate
>>them manually (IMO that's not a favourable situation).
> 
> 
> why not? they document themselves, it is evident what they do, i can
> modify them by just looking at them and grokking the general idea.

What if I implement a Publication class which stores the configuration
options (proxies, languages) in a JCR repository, so that they can be
backed-up and recovered together with the content? If other components
rely on the config file, you'll end up with trouble.

That was just an example. Components must communicate through interfaces,
everything else has no future :)


>>>the current java code does nothing else.
>>
>>Because the API doesn't offer the corresponding interfaces, due to the
>>fact that publication templating is quite new and not yet mature.
> 
> 
> do you and the other developers consider this very important for the 1.4
> release, or are there more pressing issues atm?

In my personal opinion, the repository layer has the top priority.
Maybe publication templating is one of the next priorities, because
I consider it one of the most valuable improvements of 1.4 over 1.2.


> if somebody could direct
> some of their time towards polishing this, i'll gladly offer my help and
> smart-ass remarks, but i can't pull it off myself.

:)
I'm very interested in this, but - as always - time is the problem ...

[...]

>>IMO Lenya is not a product that you just use. It could be someday in
>>the future, but this is a long way. We carry a quite large burden of
>>a lack of modularization and well-defined interfaces, lots of scripting
>>and patching. My major intention is to reduce that to a clean Java API
>>which can be used to develop applications.
> 
> 
> understandable.
> 
> but all the basic gui stuff is there, lenya is very usable already. i
> just don't see why common tasks should require custom java code by design.
> 
> since it seems that gui programming is the hardest, may i suggest the
> following priority:

> * get the java core api completed and polished

+1, that's the job of the Lenya developers.

> * make all the implemented features accessible through config files

IMO that's not necessary, see below.

> * eventually extend the gui to allow access to those new features, if
> feasible

That should be the job of the integrator. If you implement your CMS,
you can implement usecases to configure whatever you need. If you want
to donate your code - great! :)


> for me the third point is not really important. i need the gui for my
> users, who have to work on the *content*. i'm content with tweaking
> config files.

Yes, but we can't guess what your GUI should look like. The university
of Zurich wants different features than the NZZ. Other Lenya users
want something entirely different. The Lenya core should make it easy
(well, reasonably easy) to implement the CMS of your choice.


>>>* extensive hacking of lenya's java core for more or less trivial
>>>functions is a problem.
>>
>>It shouldn't be necessary to "hack the core". Publications should IMO be
>>implemented using the core (repository) API and a set of modules for
>>specific functionality (particular resource types etc.).
>>
>>
>>>even if i were a lot more java-capable than i
>>>am, i would be reluctant to do it, since it is a maintenance burden
>>>later on. (you might argue there's modularization and all, but still: if
>>>i saw the need to add or modify java code, i would try to do it in
>>>cooperation with the lenya devs, make it generally useful and try to get
>>>it accepted into the tree if at all possible.)
>>
>>OK - IMO it's just the other way round. If you use Java, you're on
>>the safe side. Your IDE informs you when something has changed, you
>>have autocomplete, easy debugging and all fancy bells and whistles.
>>If you're dealing with XML-based configuration and patching, you're
>>quite on your own. But, of course, this is just my point of view :)
> 
> 
> different worlds. i do unix administration, you do java development. me
> tarzan, you jane. or maybe the other way round. :-D
> 
> still, users should feel comfortable with lenya even if they don't boot
> their machine directly into eclipse ;)
> 
> i'll shut up now and look forward to your comments.

Again, your thoughts are really appreciated :)
I hope I don't scare you away, my intention is just to learn from earlier
mistakes and share my experience.

-- Andreas


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org


Re: RFC: suggestions for a ConfigurableInstantiator (1.4 document templating)

Posted by Andreas Hartmann <an...@apache.org>.
Jörn Nettingsmeier wrote:
> Andreas Hartmann wrote:
> 
>> If the reason for the configuration options is that the API required
>> for implementation is too complex and too hard to understand, than
>> I'd prefer to simplify and clean up the API.
> 
> 
> agreed.
> 
> do you think it could ultimately be made so friendly that i can just 
> look at one .java file without actual java or api knowledge, discover 
> patterns in it recognize stuff i know from elsewhere (like object 
> properties having the same name as xml elements in config files etc.) 
> and make useful (if simple) modifications at once?

I imagine something like the JCR API, but more high-level (documents
and meta data instead of nodes and properties, adding workflow
functions, notification etc.)

You'd read the API documentation, component diagrams and some
tutorials to get started.


[...]

>> Do you mean the fact that the publication's name and description are set?
>> IMO this is generic enough to implement it as the default behaviour.
> 
> 
> nothing is ever "generic enough".

Exactly my words. Not generic enough for everything, but generic enough
to use it as a default.


> if a default behaviour can't be 
> overridden, it's a bug. ("bug" being anything that requires touching 
> java, as per solprovider's very useful definition.)

:)

Imagine a Lenya application where you want to insert data from a custom
business application into a SAX stream. This requires writing a transformer.
Is this a bug?


>> If you want to change it - why not override the Java class? That's
>> done in a few minutes, if the base class is designed for inheritance
>> (small methods, template methods etc.)
> 
> 
> it's good to know that this is so easy. but in my world, you don't write 
> custom code. you provide patches/enhancements that are so well designed 
> and generic that the developers will want to include it into their tree.

IMO lots of very good patches have been provided in this project as well.
We have a lot of nice functionality. But I haven't yet finished a project
without writing custom Java code.

[...]

>> Like so often, it's about people and not about the code :)
> 
> 
> but users will take my path by default. the first thing you see is the 
> gui, then you read sitemaps, then you change xslts, then you change 
> sitemaps. this comes natural.
> otoh, trying to grok and hack on the java code means crossing a huge and 
> frightening barrier.

For me it's the other way round. Before dealing with scripting and
configuration options which I'm not familiar with, I look at the Java
API of a product to learn about the architecture. I rather use the top-down
approach when I'm confronted with a framework.


> <snip>
> 
>>> imho the servlet should provide all necessary functions (the
>>> "mechanism"), but it should not second-guess the user's needs and
>>> implement one particular behaviour ("policy").
>>> the instantiator needs to be so general that most lenya users never need
>>> to touch it. all its power must be accessible through the config file.
>>
>>
>> Hmmm, I don't share this opinion. We followed this strategy for a long
>> time, and it caused a lot of problems.
> 
> 
> can you point me to mailing list threads where i can learn more about 
> these problems?

I rather know them from my own projects and from workshops with customers.
Some examples:

Notification

Many people ask how to enable notification. There is a configuration file
(notification.xconf), which allows to configure certain messages and supports
some basic tags, e.g. to include the published document's URL. When a customer
wants additional information (e.g. the publishing time) in the mail, or wants
to specify a CC to the manager, or send messages using IRC, you can tweak and
extend the configuration options. But this is a never-ending story.

Workflow

The workflow provides configuration using an XML file. We chose this option
(in favor of implementation) because we thought limiting to DFAs is not a
problem in a CMS application. People ask how they can add notification actions,
custom conditions and other functionality to workflow transitions. This is just
not possible in some casese, because the configuration is not sophisticated
enough (you can't pass custom parameters etc.). The workflow description
languages I'm aware of which are capable of such things are so complex it
takes days to get a basic grasp of them.

Tasks

We made tasks configurable and nestable instead of requiring to implement
them as components. I already mentioned some of the disadvantages.


I'll try to find some threads in the mailing list archives.


[...]

-- Andreas


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org


Re: RFC: suggestions for a ConfigurableInstantiator (1.4 document templating)

Posted by Jörn Nettingsmeier <po...@uni-duisburg.de>.
Andreas Hartmann wrote:
> If the reason for the configuration options is that the API required
> for implementation is too complex and too hard to understand, than
> I'd prefer to simplify and clean up the API.

agreed.

do you think it could ultimately be made so friendly that i can just 
look at one .java file without actual java or api knowledge, discover 
patterns in it recognize stuff i know from elsewhere (like object 
properties having the same name as xml elements in config files etc.) 
and make useful (if simple) modifications at once?

xml/xsl files and scripts are like this. if the java api can be like 
this too, i'll be fine. (that is, if i can find the actual code file 
behind ten thousand layers of indirection ;).

<snip>

>>> should instead be
>>>
>>>  publication.setName(...);
>>>  publication.setDescription(...);
>>
>>
>> that is convincing.
>>
>> but it should be configurable in an xml file, not hardcoded in java.
>> do you agree?
> 
> Do you mean the fact that the publication's name and description are set?
> IMO this is generic enough to implement it as the default behaviour.

nothing is ever "generic enough". if a default behaviour can't be 
overridden, it's a bug. ("bug" being anything that requires touching 
java, as per solprovider's very useful definition.)

> If you want to change it - why not override the Java class? That's
> done in a few minutes, if the base class is designed for inheritance
> (small methods, template methods etc.)

it's good to know that this is so easy. but in my world, you don't write 
custom code. you provide patches/enhancements that are so well designed 
and generic that the developers will want to include it into their tree.

this leads to lean and mean code and a user community that actually uses 
the same stuff. custom setups are a maintenance nightmare, no matter how 
shiny your IDE is - they will fragment your user community, make support 
very hard, make bug reports very spurious and hard to reproduce.

just look at the samba-user list for a good example. no two people have 
the same setup (albeit for different reasons), and more than half of the 
posts go unanswered. the bugzilla is a bloody fscking mess, each bug 
requires three questions from a developer to determine whether it is 
even a genuine samba bug.

plus: customization via config files is always done "as intended". if i 
touch java, i will have to become familiar with lenya's java slang 
first, otherwise i'm likely to produce a kludgy, un-idiomatic solution.

>> so ++votes for clean access to publication properties via the java api
>> exclusively, but please please give me a config file to control it.
> 
> I'm still not quite sure - what would the config file contain?

see my initial post, ignore my syntax knockup.

and the best part is: we can ship a default instantiation.xconf that 99 
out of 100 would never ever want to change :)
but they can read it and understand at a glance how instantiation works 
and what possibilites for customization it has.

>>> The same should apply to policies etc. The access controller should be
>>> configurable using the API and create configuration files whenever it
>>> considers this appropriate. If Lenya supports instanciation of
>>> publications during run-time, it should also allow this without copying
>>> and patching any configuration files.
>>
>>
>> agreed.
>>
>> i guess the main difference is that, being new to lenya and java
>> servlets, i'm working from the configuration files downwards, and you
>> start from your java IDE upwards, so naturally our opinions about what
>> is easiest and most elegant would differ ;)
> 
> Like so often, it's about people and not about the code :)

but users will take my path by default. the first thing you see is the 
gui, then you read sitemaps, then you change xslts, then you change 
sitemaps. this comes natural.
otoh, trying to grok and hack on the java code means crossing a huge and 
frightening barrier.

<snip>

>> imho the servlet should provide all necessary functions (the
>> "mechanism"), but it should not second-guess the user's needs and
>> implement one particular behaviour ("policy").
>> the instantiator needs to be so general that most lenya users never need
>> to touch it. all its power must be accessible through the config file.
> 
> Hmmm, I don't share this opinion. We followed this strategy for a long
> time, and it caused a lot of problems.

can you point me to mailing list threads where i can learn more about 
these problems?

<snip>

>> and to become really usable, instantiation needs those features i
>> described in my initial post, namely a detailed description of which
>> properties should be copied from the template and which ones referenced,
>> and if copied, which alterations must be made.
>>
>> <snip>
>>
>>>> the instantiation of a publication is by nature a direct 
>>>> manipulation of
>>>> its configuration.
>>>
>>> Yes, it is a manipulation of the configuration, but it should happen
>>> only using well-defined interfaces. publication.xconf and 
>>> publication.xml
>>> are implementation details, although the documentation advises to
>>> manipulate
>>> them manually (IMO that's not a favourable situation).
>>
>>
>> why not? they document themselves, it is evident what they do, i can
>> modify them by just looking at them and grokking the general idea.
> 
> What if I implement a Publication class which stores the configuration
> options (proxies, languages) in a JCR repository, so that they can be
> backed-up and recovered together with the content? If other components
> rely on the config file, you'll end up with trouble.
> 
> That was just an example. Components must communicate through interfaces,
> everything else has no future :)

i need to get used to that java spirit, but my stomach lining tells me 
to watch out. when i started with computers, "everything was a file".

looks like we have different opinions on this topic.

a little later in your post you talk about GUI customization, and how 
that could never be achieved by "generic" java and config files.

agreed. only a card-punching troglodyte would consider that. for GUIs, 
OO design is certainly The Way(tm), and this has to happen inside java 
code.

but for other things, it's often overkill and adds complexity imho.

>> still, users should feel comfortable with lenya even if they don't boot
>> their machine directly into eclipse ;)
>>
>> i'll shut up now and look forward to your comments.
> 
> Again, your thoughts are really appreciated :)
> I hope I don't scare you away, my intention is just to learn from earlier
> mistakes and share my experience.

i'm not easily scared. ;)

-- 
"Open source takes the bullshit out of software."
	- Charles Ferguson on TechnologyReview.com

--
Jörn Nettingsmeier, EDV-Administrator
Institut für Politikwissenschaft
Universität Duisburg-Essen, Standort Duisburg
Mail: pol-admin@uni-duisburg.de, Telefon: 0203/379-2736

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org