javax.jcr.RepositoryFactory Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of aem-sdk-api Show documentation
The Adobe Experience Manager SDK
The newest version!
/*
 * Copyright 2008 Day Management AG, Switzerland. All rights reserved.
 */
package javax.jcr;

import java.util.Map;

/**
 * RepositoryFactory is a factory for Repository
 * objects.
 * 
 * An implementation of this interface must have a zero-argument public
 * constructor. Repository factories may be installed in an instance of the Java
 * platform as extensions, that is, jar files placed into any of the usual
 * extension directories. Factories may also be made available by adding them to
 * the applet or application class path or by some other platform-specific
 * means.
 * 

 * A repository factory implementation should support the Java Standard Edition
 * Service Provider mechanism, that is, an implementation should include the
 * file META-INF/services/javax.jcr.RepositoryFactory. This file
 * contains the fully qualified name of the class that implements
 * RepositoryFactory.
 * 

 * Examples how to obtain repository instances
 * 

 * Explicitly specifying the repository factory implementation: 
 * 
 *   Map parameters = new HashMap();
 *   parameters.put("com.vendor.address", "vendor://localhost:9999/repo");
 *   RepositoryFactory factory = (RepositoryFactory) Class.forName("com.vendor.RepositoryFactoryImpl");
 *   Repository repo = factory.getRepository(parameters);
 * 

 * 
 * 
 * Using ServiceLoader from Java SE 6: 
 * 
 *   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;
 *     }
 *   }
 * 

 * 
 * Note: on Java SE prior to version 6, one may use the class
 * javax.imageio.spi.ServiceRegistry to look up the available
 * RepositoryFactory implementations.
 *
 * @since JCR 2.0
 */
public interface RepositoryFactory {

    /**
     * Attempts to establish a connection to a repository using the given
     * parameters.  Parameters are passed in a Map
     * of String key/value pairs. The keys are not specified by JCR
     * and are implementation specific. However, vendors should use keys that
     * are namespace qualified in the Java package style to distinguish their
     * key names. For example an address parameter might be
     * com.vendor.address.  
 The implementation must return
     * null if it does not understand the given parameters. The
     * implementation may also return null if a default repository
     * instance is requested (indicated by null
     * parameters) and this factory is not able to identify a
     * default repository.   An implementation of this method must be
     * thread-safe.
     *
     * @param parameters map of string key/value pairs as repository arguments
     *                   or null if none are provided and a client wishes to connect
     *                   to a default repository.
     * @return a repository instance or null if this implementation
     *         does not understand the passed parameters.
     * @throws RepositoryException if if no suitable repository is found or
     *                             another error occurs.
     */
    public Repository getRepository(Map parameters) throws RepositoryException;
}