NAME

Java::JCR::Jackrabbit - Java::JCR connector for Jackrabbit

SYNOPSIS

  my $repository = Java::JCR::Jackrabbit->new;

  # Or if you'd like to be more specific:
  my $other_repository 
      = Java::JCR::Jackrabbit->new('other/repository.xml', 'other');

DESCRIPTION

This is a simple wrapper for org.apache.jackrabbit.core.TransientRepository. This creates a transient Jackrabbit repository using this class. To learn more about this class, see the Jackrabbit documentation:

  http://jackrabbit.apache.org/
  http://jackrabbit.apache.org/api-1/org/apache/jackrabbit/core/TransientRepository.html

ACCESSING A JACKRABBIT REPOSITORY

This package provides a new method, which returns a repository object that's ready to use. There are two forms for using new:

1. With no arguments, Jackrabbit builds a repository using default values. It will construct a Derby-based repository in the local file system using a repository directory named repository within the current working directory. It will also create a default repository configuration file in the current directory named repository.xml.

     my $repository = Java::JCR::Jackrabbit->new;

   This is the fastest and easiest way to get started. However, the Derby database is written in Java and isn't very fast. It's great for quickly getting started, but I wouldn't recommend it for most production environments.

   You can use this version of the constructor, but create a file named repository.xml before performing the first login to the database. See the Jackrabbit documentation for more information on how to build such a configuration file.

2. The second form requires exactly two arguments to the new method. The first is the name of the configuration file to use and the second is the directory to use as the repository home directory. This can be used to connect to repositories named something different or not in the current working directory.

     my $repository = Java::JCR::Jackrabbit->new('config.xml', 'jackrabbit');

   If the repository doesn't exist, the same action as happens for the first form happens, Jackrabbit creates a generic configuration and directory for storing a Derby-based database, but using the file and directory names you specify instead of repository.xml and repository.

   You can customize the configuration as suggested above as well.

CUSTOM NODE TYPES

There is an additional method provided by this package that allows your Perl program to register custom node types with Jackrabbit.

The JCR (as of JSR 170) does not specify a mechanism for creating custom node types. Therefore, use the register_node_types() method, to do so:

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

  Java::JCR::Jackrabbit->register_node_types($session, 'nodetypes.cnd');

The register_nodetypes() method takes two arguments:

1. The first argument is the session object to use to register the node types. This should be a session that has permission to create node types.

2. The second argument is the file name of a file formatted according to the Compact Namespace and Node Type Definition (CND) format used by Jackrabbit (see http://jackrabbit.apache.org/doc/nodetype/cnd.html).

After this method returns, all the custom node types found in the given CND file should be registered with Jackrabbit.

Here are a few additional cautionary notes you should consider when using this method:

• This implementation registers any non-reserved namespace found in the CND file that isn't already registered. It assumes that a registered prefix is mapped to the correct URI and doesn't do anything to verify whether this is actually true.

• This implementation registers any nodetype found in the CND file that isn't already registered. It assumes that a registered node type hasn't changed and does nothing to check to see if this is actually true.

This code is very basic and is only intended to let you get your nodetypes registered with a minimum of fuss. If you more complex handling of node type or namespace registration, you should write your own Java code to do so.

If you want that code to be accessible from Perl and are not sure where to get started or just need something to start with, see the source of the Java::JCR::Jackrabbit package. The Java class used to perform namespace and node type registration is defined within this package. This code was originally taken from the Jackrabbit documentation and modified to make it work here.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2006 Andrew Sterling Hanenkamp <hanenkamp@cpan.org>. All Rights Reserved.

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.