[Jackrabbit Wiki] Update of "JackrabbitOnGlassfish" by GustavoOrair

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jackrabbit Wiki" for change notification.

The "JackrabbitOnGlassfish" page has been changed by GustavoOrair:
http://wiki.apache.org/jackrabbit/JackrabbitOnGlassfish

Comment:
Creating an specific Glassfish page to deploy JackRabbit JCA on Glassfish

New page:
This document describes how to 
 * Deploy Jackrabbit on Glassfish with JCA.
 * Access the repository from session beans

Feel free to make changes to this document. 

== Deploy Jackrabbit with JCA ==
 1. If you have not done so already, [[http://jcp.org/aboutJava/communityprocess/final/jsr283/index.html|download]] the JCR 2.0 specification.
 1. Copy the jcr-2.0.jar from the specification package to {{{$GLASSFISH_HOME/domains/$DOMAIN_NAME/lib}}}. Remember that you must not include the jcr jar in any local client application at the risk of getting ClassCastExceptions when trying to access the repository through JNDI.
 1. Restart the Glassfish domain.
 1. Download the latest [[http://jackrabbit.apache.org/downloads.html|Jackrabbit JCA archive]] and deploy it either through the Glassfish Admin console or by asadmin command line deploy.
 1. Create the Connection pool either through Connector -> Connector Connection Pool or by asadmin command line:
{{{
  bin/asadmin create-connector-connection-pool --raname $rar-name --connectiondefinition javax.jcr.Repository --property HomeDir=$homeDir --description "Connection Pool" jcr_connection_pool
}}}
   * Change the {{{rar-name}}} setting to match the actual name of the jackrabbit-jca RAR file you downloaded and deployed above
   * Change the {{{homeDir}}} property to match the folder where you want Jackrabbit to store its files

     /!\ If you change the HomeDir property, you should not use repositoryURI property.
 1. Create the Connector Resource (JNDI name) to access the Connection Pool either through Connector -> Connector Resources or by asadmin command line:
{{{
  bin/asadmin create-connector-resource --poolname jcr_connection_pool --description "JNDI Name to access the Connector Connection Pool jcr_connection_pool" jcr/Repository
}}}
Now, jackrabbit is running and available through JNDI at {{{java:jcr/Repository}}} (or whatever other JNDI name you specified). 

    /!\ If you re using Glassfish 3.1 or above you should check ClassLoading Policy before trying to access the JCR Repository properly.

=== Common problems faced while configuring jackrabbit on Glassfish ===
1. I get some issues with Glassfish 3.1 ClassLoadingPolicy. I sent this question to Glassfish Users list[[http://www.java.net/forum/topic/glassfish/glassfish/jackrabbit-jca-classloading-issues]].

If Glassfish ClassLoader didn't find the libraries inside the jackrabbit JCA rar.
JackRabbit JCA is shipped with JackRabbit Core inside that provides the "server implementation". But the class with this implementation was not found by the classloader.

It happens because by default Glassfish 3.1 or above is configured with the derived classloading policy [[http://www.java.net/external?url=http://download.oracle.com/docs/cd/E18930_01/html/821-2418/bealr.html#gjjyy]].
It means that the Applications access resource adapters based on references in their deployment descriptors. These references can be resource-ref, resource-env-ref, resource-adapter-mid, or equivalent annotations.
If no references are found on the deployment descriptors, the classes defined inside the Resource Adapter (JackRabbit-JCA) will not be found by the Applications ClassLoader.

If you do not want to define references in deployment descriptors or annotations, you may change the class-loading-policy setting to global.
To configure this setting, use the asadmin set command. For example:
{{{
asadmin set server.connector-service.class-loading-policy="global"
}}}

For details, see the the Oracle GlassFish Server 3.1-3.1.1 Application Development Guide [[http://www.java.net/external?url=http://download.oracle.com/docs/cd/E18930_01/html/821-2418/bealr.html#gjjyy]] or the Oracle GlassFish Server 3.1-3.1.1 Reference Manual [[http://docs.oracle.com/cd/E18930_01/html/821-2433/index.html]].