ResourceHelper progress

[Andrew Wills]

Hey folks,

I wanted to send out a note describing the progress I've been making
on the ResourceHelper concept I talked about a few days ago.
Everything described herein is implemented in my local SNAPSHOT of
cernunnos 1.1.0 (trunk).

To recap... the ResourceHelper provides a standard way to reference
resources by CONTEXT and LOCATION (something we do a lot); it's
designed to make CRN components behave more consistently and
predictably, as well as provide new flexibility in some important
circumstances (e.g. ${doc}, see below).

Here's how it works:
- each task or phrase has a CONTEXT and a LOCATION reagent
- LOCATION specifies the path to a resource; the default is the
value of the 'Attributes.LOCATION' request attribute
- LOCATION may be absolute or relative
- if it is relative, it gets evaluated from the CONTEXT reagent
- the default CONTEXT is the value of the 'Attributes.CONTEXT'
request attribute, if present, or (if not) the value of
'Attributes.ORIGIN'
- together, CONTEXT and LOCATION describe a URL of any supported
scheme, which means anything supported by the Java environment *plus*
'classpath:/' and things like 'c:\' on windows.

The ResourceHelper.java file itself is implemented. A copy of it is
attached to this note.

The other changes I have prepared involve tasks and phrases that were
'enhanced' to use this new utility. These fall basically into 3
categories, which I will describe now...

Category 1
----------------
These are Tasks and Phrases that already used Attributes.ORIGIN as a
default CONTEXT and Attributes.LOCATION as a default LOCATION; they
are:
- ${cecksum}
- ${crn}
- <crn>
- <properties>
- <spring-beans>

These needed to change only slightly... by picking up
Attributes.CONTEXT as the primary default for CONTEXT. I consider
this change in behavior to be low-risk enough that I figure we don't
need to deprecate the old components and replace them with new ones
(with different names).

Category 2
----------------
These Tasks and Phrases already used Attributes.CONTEXT as the
'primary' default, but for their second default they used the
directory where Java is currently executing; also they already used
Attributes.LOCATION for LOCATION. They are:
- <archive-iterator>
- <copy-file>
- <extract-archive>

These needed to change slightly also... by picking up
Attributes.ORIGIN as the 'backup' default (after Attributes.CONTEXT).
Again, I figured this change is low-risk enough that we don't need to
deprecate the old items and replace them with newly-named items.

Category 3
----------------
These items don't fit either of the above patterns; The changes in
behavior that would be required to move them to the new pattern are
probably too risky to existing CRN XML. They are:
- ${doc}: the Java working dir was the (only) default for CONTEXT,
so existing CRN XML would break in any situation where a relative
LOCATION was used; this is a bigger change/surprise than either of
the 2 previous categories, so this phrase was deprecated and replaced
with ${parseXml}, which uses the new pattern
- <delete-file>: would be same as copy-file, but it uses a FILE
reagent instead of LOCATION, so existing CRN XML would break; I need
to deprecate and replace this one
- <xslt>: Uses CONTEXT for both source document and stylesheet;
needs to be deprecated and replaced with an impl that doesn't
auto-parse a LOCATION doc (we have phrases to do this) or write a file
to disk (that's what SUBTASKS are for)

I'm probably going to continue working on <delete-file> and <xslt>
before I commit, giving myself a bit more time to stew over these
changes and make sure I'm not overlooking something.

Please speak up if you think this is the right way or the wrong way to
bring this enhancement into being.

cheers,

drew wills

[Drew Wills]

Hey folks,

I just wrapped up the ResourceHelper stuff. After my earlier email I
found out that I had gotten a little (maybe more than a little) ahead
of myself in this area, so I'm going to interweave some updates with
the text of the previous email. This way you'll be up to speed on the
actual changes (hint -- they're much smaller than the earlier plan).

On Nov 24, 4:24 pm, "Andrew Wills" <wills.d...@gmail.com> wrote:
> Hey folks,
>
> I wanted to send out a note describing the progress I've been making
> on the ResourceHelper concept I talked about a few days ago.
> Everything described herein is implemented in my local SNAPSHOT of
> cernunnos 1.1.0 (trunk).
>
> To recap... the ResourceHelper provides a standard way to reference
> resources by CONTEXT and LOCATION (something we do a lot);  it's
> designed to make CRN components behave more consistently and
> predictably, as well as provide new flexibility in some important
> circumstances (e.g. ${doc}, see below).
>

I quickly learned (in testing) that consistency is only useful to a
point. There's a reason that some components took their CONTEXT from
Attributes.ORIGIN while others took it from the current working
directory (or Attributes.CONTEXT): some components naturally want to
use resources from the source tree, and some from a set of files
you're working on.

Consider <xslt> -- you probably want to read the stylesheet document
relative to the CRN XML you're executing. For ${checksum}, on the
other hand, you probably want to read relative to Attributes.CONTEXT
(if set) or the directory you're working from. In either case, you
can get the opposite behavior just by specifying an absolute LOCATION.

So then... none of the behavior changes described above were adopted
in the end -- not a single one. Every component behaves exactly as
before, though *most* of them now use the ResourceHelper API. Those
(few) that don't can't do so, at least not easily, for reasons of
backwards compatibility, and should be addressed on a case-by-case
basis in the near term.

Cheers,

drew wills