Code Index:

package Java::JCR
- import_my_packages
EOF

NAME

Java::JCR - Use JSR 170 (JCR) repositories from Perl

SYNOPSIS

  use Java::JCR;
  use Java::JCR::Jackrabbit;

  my $repository = Java::JCR::Jackrabbit->new;
  my $session = $repository->login(
      Java::JCR::SimpleCredentials->new('username', 'password')
  );

  my $root = $session->get_root_node;
  my $node = $root->add_node('foo', 'nt:unstructured');
  $node->set_property('bar', 10);
  $node->set_property('baz', 'blah');
  $node->set_property('qux', 4.8');
  $session->save;

DESCRIPTION

The JSR 170 specification describes a Java-based API for access hierarchical databases. This is generally referred to by the abbreviation JCR, which is an abbreviation for Content Repository API for Java Technology Specification.

The biggest OSS implementation, as of this writing, is Jackrabbit, which is a project at the Apache Software Foundation, http://jackrabbit.apache.org/. Currently, this library allows Perl programmers to develop using the JCR and Jackrabbit, though, there's no reason why connectors can't be written for other implementations, such as Jaceira, CRX, eXoplatform, etc. The JCR library wrappers included are not at all specific to Jackrabbit.

JAVA DOCUMENTATION

At this time, this library does not have documentation for any of the methods used. However, the Perl documentation included with each package links to the Java documentation for that package. That documentation can be used with this API by keeping the following in mind:

Each javax.jcr.* package is mapped into the Java::JCR::* namespace using Perl-style package names.
By loading the parent package, you load all nested packages. That is, by loading this package, Java::JCR, you load every immediate sub-package under Java::JCR, such as Java::JCR::Repository, Java::JCR::Session, and Java::JCR::Node.

If you want to access classes in one of the other packages, just load the parent. For example, if you want to load all the JCR classes, you need these bit of code:
```
  use Java::JCR;
  use Java::JCR::Lock;
  use Java::JCR::Nodetype; # <!-- N.B. letter case is a little funny here
  use Java::JCR::Observation;
  use Java::JCR::Query;
  use Java::JCR::Util;
  use Java::JCR::Version;
```
```
  # And the Jackrabbit connector:
  use Java::JCR::Jackrabbit;
```

All Java method names, which are in camel-case (theyHaveHumpsInTheMiddle), have been translated to use the more common (in Perl) lower-case with underscores.

Thus, the following snippet in Java:

  Session session = repository.login();
  Node root = session.getRootNode();
  Node node = root.getNode("some/node/in/the/tree");
  Property property = node.getProperty("myProperty");

becomes this iin Perl:

  my $session = $repository->login;
  my $root = $session->get_root_node;
  my $node = $root->get_node("some/node/in/the/tree");
  my $property = $node->get_property("myProperty");

this includes abbreviations as well, so importXML() and <getNodeByUUID()> in Java are import_xml() and get_node_by_uuid() in Perl.

IMPLEMENTATION

Here's my opportunity to plug Inline::Java. It works very well and made this possible. There are some deficiencies in exception handling and other places that one would expect difficulties, but all-in-all it works very well. The actual mapping to Java is done through this facility.

In addition, I've created a pure-Perl wrapper object for each to allow me to easily cope with problems in the mappings and to provide an opportunity to hook in better features.

For example, the Java Date object isn't really an ideal solution for Perl coders. Therefore, it is planned that dates be mapped to a Perl equivalent (probably with the option of choosing your favorite since there are quite a few to choose from). This wouldn't be possible if the mapping was just the raw Inline::Java one.

The wrappers also help smooth off some of the rough edges of the mapping from Java.

BUGS

Some things don't work. As of this writing, this is the first release, and I've only done just enough to get the first three "hops" from the Jackrabbit documentation going. You should be able to connect to a repository, login, get nodes and properties by path, create nodes and properties, and import XML using the examples on the Jackrabbit web site. (Perl ports of those are in the ex/ directory of the distribution, by the way.)

If you would like to contribute, let me know of a bug, or make a comment, please send me email at <hanenkamp@@cpan.org> or post a ticket to CPAN RT at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Java-JCR.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.