JndiConfiguration.java

/*
 * Copyright 2008 Niclas Hedhman.
 *
 * Licensed  under the  Apache License,  Version 2.0  (the "License");
 * you may not use  this file  except in  compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed  under the  License is distributed on an "AS IS" BASIS,
 * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
 * implied.
 *
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.qi4j.entitystore.jndi;

import org.qi4j.api.common.Optional;
import org.qi4j.api.common.UseDefaults;
import org.qi4j.api.configuration.ConfigurationComposite;
import org.qi4j.api.property.Property;

/**
 * Configuration for the JNDI EntityStore.
 * <p>
 * Many of the Property instances are passed on to the <code>javax.naming.InitialContext</code> as is, and the javadoc
 * below mirrors the meaning found for the constants in the <code>javax.naming.Context</code> interface.
 * </p>
 */
public interface JndiConfiguration extends ConfigurationComposite
{

    /**
     * If set to read-only mode, then no creation and no updates of the EntityStore will be allowed.
     *
     * @return if true, then don't allow updates of the underlying store. Such operations will throw a
     *         ReadOnlyEntityStoreException.
     */
    @UseDefaults Property<Boolean> readOnly();

    /**
     * Instance version property.
     *
     * If the EntityStore is NOT readonly, each entry must have an attribute to store the instance version. This
     * Property names that attribute available in all entries.
     *
     * If not specified, the atttribute used will be "instanceVersion".
     *
     * @return The name of the attribute where to store the instance version number.
     */
    @Optional Property<String> versionAttribute();

    /**
     * Last modified property.
     * If the EntityStore is NOT readonly, each entry must have an attribute to store the last modified date.
     * This property names that attributes in all entries.
     *
     * If not specified, the attribute used will be "lastModifiedDate".
     *
     * @return The name of the attribute where to store the last modified date.
     */
    @Optional Property<String> lastModifiedDateAttribute();

    /**
     * QualifiedType attribute.
     *
     * If the EntityStore is going to support the Iterable interface, it must store the qualifiedType in an
     * attribute in the entry. This is also required for non-readOnly stores.
     *
     * @return The name of the attribute where to store the qualifiedType.
     */
    @Optional Property<String> qualifiedTypeAttribute();

    /**
     * Whether Turbo Mode for serialization should be used or not.
     *
     * @return Whether turbo mode is enabled or not.
     */
    @UseDefaults Property<Boolean> turboMode();

    /**
     * The Distinguished Name of the base.
     * All creation and retrieval will occur in this directory.
     *
     * @return The property of the DN to the directory of operation.
     */
    Property<String> baseDN();

    /**
     * This will provide the name of the attribute where the binary blob of the properties will be stored.
     * <p>
     * If there is no attribute name provided, each property will be stored in its own attribute, of the same
     * name as the property itself.
     * </p>
     * <p>
     * Note: Associations are always stored in attributes with the same name as the attribute itself. It doesn't
     * allow for aggregated/collapsing of all into a single attribute as is possible for property data.
     * </p>
     *
     * @return The property containing the attribute name, or empty if property collapsing should not occur.
     */
    @Optional Property<String> propertyAttribute();


    /**
     * The attribute to use for storing the identity in an entry.
     *
     * <p>
     * If there is no attribute name provided, then use "uid" as the identity attribute in the entry.
     * </p>
     *
     * @return
     */
    @UseDefaults Property<String> identityAttribute();

    /**
     * Property for specifying the authoritativeness of the service requested.
     * <p>
     * If the value of the property is the string "true", it means that the access is to the most authoritative
     * source (i.e. bypass any cache or replicas). If the value is anything else, the source need not be (but may be)
     * authoritative. If unspecified, the value defaults to "false".
     * </p>
     *
     * @return The property containing the string "true" or "false", whether the source is authorative or not.
     */
    @Optional Property<String> authorative();

    /**
     * Property for specifying the batch size to use when returning data via the service's protocol.
     * <p>
     * This is a hint to the provider to return the results of operations in batches of the specified size, so the
     * provider can optimize its performance and usage of resources. The value of the property is the string
     * representation of an integer. If unspecified, the batch size is determined by the service provider.
     *
     * @return The property that contains the batch size.
     */
    @Optional Property<String> batchSize();

    /**
     * Property for specifying the list of control factories to use.
     * <p>
     * The value of the property should be a colon-separated list of the fully qualified class names of factory
     * classes that will create a control given another control.
     * </p>
     *
     * @return The property that possibly contains the control factory(ies) class names.
     */
    @Optional Property<String> controlFactories();

    /**
     * Property for specifying the DNS host and domain names to use for the JNDI URL context (for example,
     * "dns://somehost/wiz.com").
     *
     * <p>
     * This property may be specified in the environment, an applet parameter, a system property, or a resource file.
     * If it is not specified in any of these sources and the program attempts to use a JNDI URL containing a DNS
     * name, a ConfigurationException will be thrown.
     * </p>
     *
     * @return
     */
    @Optional Property<String> dnsUrl();

    /**
     * Property for specifying the initial context factory to use.
     * <p>
     * The value of the property should be the fully qualified class name of the factory class that will create an
     * initial context. If it is not specified in any of these sources, NoInitialContextException is thrown when an
     * initial context is required to complete an operation.
     * </p>
     *
     * @return
     */
    @Optional Property<String> initialContextFactory();

    /**
     * Property for specifying the preferred language to use with the service.
     *
     * <p>
     * The value of the property is a colon-separated list of language tags as defined in RFC 1766. If this property
     * is unspecified, the language preference is determined by the service provider.
     * </p>
     *
     * @return
     */
    @Optional Property<String> language();

    /**
     * Property for specifying the list of object factories to use.
     * <p>
     * The value of the property should be a colon-separated list of the fully qualified class names of factory classes
     * that will create an object given information about the object.
     * </p>
     *
     * @return
     */
    @Optional Property<String> objectFactories();

    /**
     * The URL string to connect to the LDAP server.
     *
     * property for specifying configuration information for the service provider to use. The value of the property
     * should contain a URL string (e.g. "ldap://somehost:389"). It may also contain connect arguments as query
     * arguments in the URL.
     *
     * @return The connection string to use to connect.
     */
    Property<String> providerUrl();

    /**
     * A property to define how referrals should be dealt with.
     * <p>
     * The value of the property is one of the following strings:
     * <code><pre>
     * "follow" follow referrals automatically
     * "ignore" ignore referrals
     * "throw" throw ReferralException when a referral is encountered.
     * If this property is not specified, the default is determined by the provider.
     */
    @Optional Property<String> referral();

    /**
     * What type of authentication should be used.
     * <p>
     * Its value is one of the following strings: "none", "simple", "strong". If this property is unspecified, the
     * behaviour is determined by the service provider.
     * </p>
     *
     * @return
     */
    @Optional Property<String> securityAuthentication();

    /**
     * The Principal passworf to log into the LDAP server.
     *
     * <p>
     * The value of the property depends on the authentication scheme. For example, it could be a hashed password,
     * clear-text password, key, certificate, and so on.
     * </p>
     *
     * @return The password to use to log in.
     */
    Property<String> securityCredentials();

    /**
     * The Principal Name to log into the LDAP server.
     *
     * @return The username to use to log in.
     */
    Property<String> securityPrincipal();

    /**
     * The Security protocol, if any, to be used.
     *
     * @return The protocol that should be used, or null if defined by the provider.
     */
    @Optional Property<String> securityProtocol();

    /**
     * Property for specifying the list of state factories to use.
     * <p>
     * The value of the property should be a colon-separated list of the fully qualified class names of state factory
     * classes that will be used to get an object's state given the object itself.
     * </p>
     *
     * @return
     */
    @Optional Property<String> stateFactories();

    /**
     * Property for specifying the list of package prefixes to use when loading in URL context factories.
     * <p>
     * The value of the property should be a colon-separated list of package prefixes for the class name of the
     * factory class that will create a URL context factory.
     * The prefix com.sun.jndi.url is always appended to the possibly empty list of package prefixes.
     * </p>
     *
     * @return
     */
    @Optional Property<String> urlPkgPrefixes();

}