Distribution of commons classes

[Jukka Zitting <ju...@gmail.com>]

Hi,

With JCR-996 and the goal of eventually integrating SPI with
Jackrabbit core there comes a question of where and how we should
bundle the various "commons" classes we have. Currently
jackrabbit-jcr-commons is the throw-in default of all utility classes
that might be useful also outside jackrabbit-core.

To better define the scope of jackrabbit-jcr-commons and related
packages, I'd like to propose the following:

1) The jackrabbit-jcr-commons package should contain generic utility
classes that work *on top of* the JCR API. The classes should handle
names and paths in string format, and use the namespace methods on
javax.jcr.Session where name manipulation is needed. The package can
also contain JCR base classes and other utilities that implement JCR
interfaces and methods in terms of other JCR API calls. Optimally the
only dependencies should be the Java 1.4 and JCR 1.0 (later 2.0).

2) The jackrabbit-jcr2spi package should contain everything that is
needed to bridge between the JCR and SPI interfaces. Optimally the
only dependencies would be Java 1.4, JCR 1.0 (later 2.0), SPI, and
possibly jackrabbit-jcr-commons and other generic things like
commons-collections and slf4j. Note that much of the functionality in
jackrabbit-jcr2spi should be usable as a generic dependency also for
"native" transient space implementations like the current
jackrabbit-core.

3) The jacrabbit-spi-commons package should contain generic utility
classes that work *below* the SPI. Optimally the only dependencies
would be Java 1.4 and SPI. This package should be usable by both
jackrabbit-core and any SPI-based JCR connectors.

I would optimally place all the string-name conversion functionality
in jcr2spi, but since at least the query parser needs that
functionality on the SPI implementation side, it might be necessary to
push that functionality down to spi-commons.

WDYT?

BR,

Jukka Zitting

Re: Distribution of commons classes

[Angela Schreiber <an...@day.com>]

hi jukka

> 1) The jackrabbit-jcr-commons package should contain generic utility
> classes that work *on top of* the JCR API. [...] Optimally the
> only dependencies should be the Java 1.4 and JCR 1.0 (later 2.0).

if i understand it properly this would include:

- JcrConstants.java

- value package:
   ValueFactoryImpl, Value implementations, ValueHelper.java

- uuid package:
   since its used by the ValueFactory (not because i think
   this is really needed on top of the JCR API).

- util package:
   Text.java, ISO8601.java, Base64.java, others? ->> see questions below.

according the the description below the
- org.apache.jackrabbit.name
package would be moved to 2) or 3).


> 2) The jackrabbit-jcr2spi package should contain everything that is
> needed to bridge between the JCR and SPI interfaces. Optimally the
> only dependencies would be Java 1.4, JCR 1.0 (later 2.0), SPI, and
> possibly jackrabbit-jcr-commons and other generic things like
> commons-collections and slf4j.
 > I would optimally place all the string-name conversion functionality
 > in jcr2spi, but since at least the query parser needs that
 > functionality on the SPI implementation side, it might be necessary to
 > push that functionality down to spi-commons.

that's what i would prefer. i think the conversion is general enough
to be placed in a commons package as long as we can make sure, that
it is not limited to a single name/path implementation.
and i think SPI commons is a better place than jcr-commons due to the
dependency to the SPI interfaces.

> 3) The jacrabbit-spi-commons package should contain generic utility
> classes that work *below* the SPI. Optimally the only dependencies
> would be Java 1.4 and SPI. This package should be usable by both
> jackrabbit-core and any SPI-based JCR connectors.

agreed. this includes from my point of view:

- the existing default implementations for
   > SPI identifier and factory
   > SPI value and factory
   > the various 'info' interfaces present in the SPI

- in addition default implementations for
   > name (and factory)
   > path (and factory)

and as stated above i would also include the

- name/path conversion
- value conversion

> WDYT?

i'm in favour of this approach.

kind regards
angela


open questions:

- the spi-commons defines an alternative ValueFactoryImpl, that does
   not force the reference-value to be a UUID and which obviously
   does not belong to the spi-commons module. can we find a solution
   for this in the jcr-commons?

- what about those util-classes that are used by a JCR-implementation
   but not by the SPI implementation?
   e.g. IteratorHelper.java
   Should those rather be in jcr-commons or in spi-commons?

- what about general utility classes such as
   ISO9075.java, XMLChar.java, Timer.java
   that don't have any dependency to jackrabbit internals but
   still are not of general use on top of JCR?

- what about the following packages in jackrabbit-jcr-commons:
   org.apache.jackrabbit.commons ?
   org.apache.jackrabbit.util.name ?
   are they used at all?

Re: Distribution of commons classes

[Julian Reschke <ju...@gmx.de>]

Angela Schreiber wrote:
> ....
> i'd like to take up the discussion regarding distribution
> of the jcr-commons-classes and the related issue JCR-996
> and come up with an proposal.
> it summarizes the findings of my initial efforts while working
> on JCR-996 on the current jackrabbit trunk. i tested the general 
> feasibility on the spi project and on parts of the jackrabbit-core.
> ...

Caveat: I only have limited insight into jackrabbit-core.

But from the perspective of reducing code duplication between the 
monolithic jackrabbit and the JCR2SPI this makes a lot of sense to me.

+1.

Best regards, Julian

Re: Distribution of commons classes

[Angela Schreiber <an...@day.com>]

hi

Stefan Guggisberg wrote:
> On 7/26/07, Jukka Zitting <ju...@gmail.com> wrote:
>> Hi,
>>
>> With JCR-996 and the goal of eventually integrating SPI with
>> Jackrabbit core there comes a question of where and how we should
>> bundle the various "commons" classes we have. Currently
>> jackrabbit-jcr-commons is the throw-in default of all utility classes
>> that might be useful also outside jackrabbit-core.
 >> [...]
>> WDYT?
> 
> +1, sounds good.
> 
> cheers
> stefan
>>
>> BR,
>> Jukka Zitting

i'd like to take up the discussion regarding distribution
of the jcr-commons-classes and the related issue JCR-996
and come up with an proposal.
it summarizes the findings of my initial efforts while working
on JCR-996 on the current jackrabbit trunk. i tested the general 
feasibility on the spi project and on parts of the jackrabbit-core.

please comment.
regards
angela


----------------------------------------------------------
jackrabbit-jcr-commons
----------------------------------------------------------

- modify without breaking existing dependencies to it.

- therefore rather deprecate than move classes related to
   internal functionality of a JCR impl.
   this mainly affects classes used for namespace handling and
   name/path conversion:

   > org.apache.jackrabbit.name.*.java
   > org.apache.jackrabbit.util.name.*.java

- in addition the following 'utility' classes:

   > org.apache.jackrabbit.util.PathMap
   > org.apache.jackrabbit.util.Locked
   > org.apache.jackrabbit.BaseException

- eventually deprecated methods that define param/return
   values to be any of the classes mentioned above

   > o.a.j.value.NameValue.valueOf(QName, NamespaceResolver)
   > o.a.j.util.ISO9075.encode(QName)
   > o.a.j.util.ISO9075.decode(QName)

- move the alternative ValueFactory implementation that
   does not require a reference value to be a UUID from
   jackrabbit-spi-commons to the o.a.j.value package.


----------------------------------------------------------
jackrabbit-spi-commons
----------------------------------------------------------

- copy classes that have been deprecated in jcr-commons
   to different packages in the spi-commons.
   e.g.

   > namespace handling      -> o.a.j.namespace
   > name/path conversion    -> o.a.j.conversion
   > creation Name/Path      -> o.a.j.name
   > o.a.j.util.PathMap      -> o.a.j.name (?)
   > o.a.j.util.Locked       -> o.a.j.lock (?)

- replace usages of QName/Path within the conversion
   and utility classes with Name/Path interfaces

- provide default factories for both Name and Path based
   on the current QName and Path classes.

- get rid of duplicate conversion functionality provided
   both by *Resolver interfaces and by *Format classes.
   i would opt for using the *Resolver interfaces.

- add o.a.j.name.NameConstants for the various predefined
   and widely used names.

- since the proposed Name/Path interfaces do currently
   not make usage of the BaseException but rather use
   RepositoryException, i would in addition suggest to
   make the various internal exceptions extend RepositoryExc.


----------------------------------------------------------
jackrabbit-spi (see JCR-996)
----------------------------------------------------------

- define Name, Path and *Factory interfaces
- change all SPI interfaces to use Name/Path interfaces
- remove dependency to jackrabbit-jcr-commons

Re: Distribution of commons classes

[Stefan Guggisberg <st...@gmail.com>]

On 7/26/07, Jukka Zitting <ju...@gmail.com> wrote:
> Hi,
>
> With JCR-996 and the goal of eventually integrating SPI with
> Jackrabbit core there comes a question of where and how we should
> bundle the various "commons" classes we have. Currently
> jackrabbit-jcr-commons is the throw-in default of all utility classes
> that might be useful also outside jackrabbit-core.
>
> To better define the scope of jackrabbit-jcr-commons and related
> packages, I'd like to propose the following:
>
> 1) The jackrabbit-jcr-commons package should contain generic utility
> classes that work *on top of* the JCR API. The classes should handle
> names and paths in string format, and use the namespace methods on
> javax.jcr.Session where name manipulation is needed. The package can
> also contain JCR base classes and other utilities that implement JCR
> interfaces and methods in terms of other JCR API calls. Optimally the
> only dependencies should be the Java 1.4 and JCR 1.0 (later 2.0).
>
> 2) The jackrabbit-jcr2spi package should contain everything that is
> needed to bridge between the JCR and SPI interfaces. Optimally the
> only dependencies would be Java 1.4, JCR 1.0 (later 2.0), SPI, and
> possibly jackrabbit-jcr-commons and other generic things like
> commons-collections and slf4j. Note that much of the functionality in
> jackrabbit-jcr2spi should be usable as a generic dependency also for
> "native" transient space implementations like the current
> jackrabbit-core.
>
> 3) The jacrabbit-spi-commons package should contain generic utility
> classes that work *below* the SPI. Optimally the only dependencies
> would be Java 1.4 and SPI. This package should be usable by both
> jackrabbit-core and any SPI-based JCR connectors.
>
> I would optimally place all the string-name conversion functionality
> in jcr2spi, but since at least the query parser needs that
> functionality on the SPI implementation side, it might be necessary to
> push that functionality down to spi-commons.
>
> WDYT?

+1, sounds good.

cheers
stefan

>
> BR,
>
> Jukka Zitting
>