ModeShape URL RFC

[bcarothers]

One of the additional features provided by JCR2 is the ability to get access to a JCR repository through a standard RepositoryFactory interface.  JCR implementations (like ModeShape) would provide their own implementation of this interface and register it as a service.  This would remove the need to have any implementation-specific code in one's application to use JCR.  Instead, you could just use a snippet like this example from the JCR2 specification:

Map parameters = new HashMap();

parameters.put("com.vendor.address", "vendor://localhost:9999/repo");

Repository repo = null;

for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {

     repo = factory.getRepository(parameters);

     if (repo != null) {

     // factory accepted parameters

     break;

}

This is easy enough to implement, but the spec doesn't say anything about what the parameters should be.  I started out with a bunch of different individual parameters (e.g., org.modeshape.jcr.CONFIG_FILE, org.modeshape.jcr.JNDI_NAME, org.modeshape.jcr.REPOSITORY_NAME), but I thought it might be better to just provide a good old JDBC-style URL.

To that end, I propose that the ModeShape 2.0 RepositoryFactory implementation take one parameter (org.modeshape.jcr.URL) with a value that matches this format:

     jcr:modeshape:<protocol>://<path>[?<repository name>]

The value of <protocol> would either be "jndi" or "file".  The <path> is either the JNDI name of the JcrEngine (if <protocol> is "jndi") or the relative or absolute path to the file or resource containing the configuration information (if <protocol> is "file").  Finally, <repository name> would be used to access a named JCR repository, but could be omitted if the JcrEngine only had one repository.

So a sample JNDI URL is: "jcr:modeshape:jndi://my/jndi/path?My Repository" and a sample file URL is "jcr:modeshape:file://src/test/resources/configRepository.xml?Test Repository Source".

Please consider this a solicitation of feedback for this approach including:

- whether it's better to go with one URL or many other parameters

- the URL format

- the parameters in the URL

Thanks in advance!

[rhauch]

Brian Carothers wrote:

... but I thought it might be better to just provide a good old JDBC-style URL.

To that end, I propose that the ModeShape 2.0 RepositoryFactory implementation take one parameter (org.modeshape.jcr.URL) with a value that matches this format:

     jcr:modeshape:<protocol>://<path>[?<repository name>]

The value of <protocol> would either be "jndi" or "file".  The <path> is either the JNDI name of the JcrEngine (if <protocol> is "jndi") or the relative or absolute path to the file or resource containing the configuration information (if <protocol> is "file").  Finally, <repository name> would be used to access a named JCR repository, but could be omitted if the JcrEngine only had one repository.

So a sample JNDI URL is: "jcr:modeshape:jndi://my/jndi/path?My Repository" and a sample file URL is "jcr:modeshape:file://src/test/resources/configRepository.xml?Test Repository Source".

Please consider this a solicitation of feedback for this approach including:

- whether it's better to go with one URL or many other parameters

- the URL format

- the parameters in the URL

Thanks in advance!

First of all, I definitely think 1 parameter like you suggest is the way to go. It's very easy to understand, especially since that single parameter is just a URL. Sure, you have to know the URL format, but you have to know that anyway.  And by using the JDBC-style query parameters, the URL can actually contain other properties, such as "repository". In fact, this is exactly how our JDBC driver implementation handles URLs.

Secondly, what if we do not prefix the URL value with "jcr:modeshape:", and instead just use "file://", "http://" and "jndi://" style URLs. I can see several benefits to this:

1. The ModeShape RepositoryFactory implementation can look for the "org.modeshape.jcr.url" property to know if it should attempt to resolve a Repository instance. This means we really don't need the "modeshape" in the URL.
2. As you propose, in the case of "jndi://", the RepositoryFactory can just translate the URL into a JNDI name.  (This is actually what our JDBC driver does; see below.)  In the case of "file://" or "http(s)://", the RepositoryFactory can just remove any query parameters and attempt to resolve to the configuration file.
3. This URL can be prepended with "jdbc:jcr:" and then supplied to our JDBC driver, which can simply delegate to the RepositoryFactory-style mechanism.

That brings us to the parameters. Rather than just assume there is a single parameter that is the name of the repository, perhaps we could use "repository={repositoryName}". It's more conventional, plus it would be compatible with our JDBC driver, which currently accepts several query parameters, including "repository", "workspace", "username" and "password". (Recall that the JDBC driver must not only obtain the Repository instance, but it must also login to obtain a Session; thus the need for the "workspace", "username" and "password" properties.)

In summary, I really like your proposal, but with a few changes that results in a single URL design that works for our JDBC driver and RepositoryFactory implementations:

<protocol>://<path>[?repository=<repository name>]

where <protocol> is "jndi", "file" or even "http" or "https"; <path> is either the JNDI name of the JcrEngine (if <protocol> is "jndi") or the relative or absolute path to the file or resource containing the configuration information (if <protocol> is "file"); and <repository name> would be used to access a named JCR repository, but could be omitted if the JcrEngine only had one repository.  Any other query parameters should be allowed, but simply ignored.

What do you think?

[bcarothers]

I like these suggestions a lot, particularly in how they'd be consistent with the JDBC driver.  I'll try to mock this up tonight.

Thanks for the feedback!  I'd love to hear others' opinions on this as well.