001/*
002 * file CqDbSet.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM 
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqDbSet
008 *
009 * (C) Copyright IBM Corporation 2004, 2008.  All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
011 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
012 */
013package com.ibm.rational.wvcm.stp.cq;
014
015import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
016
017import javax.wvcm.ResourceList;
018import javax.wvcm.WvcmException;
019import javax.wvcm.PropertyNameList.PropertyName;
020
021import com.ibm.rational.wvcm.stp.StpRepository;
022import com.ibm.rational.wvcm.stpex.StpExEnumeration;
023import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
024
025
026/**
027 * A collection of user database resources. The user databases are known by
028 * simple names within a CqDbSet, and thus the CqDbSet is fundamentally useful for
029 * enumerating those database names.
030 * <p>
031 * The user-friendly specification for the location of a db-set has the form
032 * <pre>
033 *  <b>cq.dbset:</b><i>&lt;db-set-name&gt;
034 * </pre>
035 */
036public interface CqDbSet
037    extends CqDb, StpRepository
038{
039    /**
040     * A list of the user databases to which the current user has access. The
041     * list is the same as that returned by
042     * getCurrentUser().getSubscribedDatabases(), but can be computed much more
043     * efficiently.
044     */
045    PropertyName<ResourceList<CqUserDb>> ACCESSIBLE_DATABASES =
046        new PropertyName<ResourceList<CqUserDb>>(PROPERTY_NAMESPACE, 
047                                                 "accessible-databases");
048
049    /**
050     * Returns the value of the {@link #ACCESSIBLE_DATABASES} property as
051     * defined by this proxy.
052     * 
053     * @return A list of the user databases that are in this DbSet. Will never
054     *         be <b>null</b>, but may be empty.
055     * 
056     * @throws WvcmException if this proxy does not define a value for the
057     *             {@link #ACCESSIBLE_DATABASES} property.
058     */
059    ResourceList<CqUserDb> getAccessibleDatabases() throws WvcmException;
060    
061    /** A list of the user databases that are in this DbSet */
062    PropertyName<ResourceList<CqUserDb>> USER_DATABASES =
063        new PropertyName<ResourceList<CqUserDb>>(PROPERTY_NAMESPACE, "user-databases");
064
065    /**
066     * Returns the value of the {@link #USER_DATABASES} property as defined by
067     * this proxy.
068     * 
069     * @return A list of the user databases that are in this DbSet. Will never
070     *         be <b>null</b>, but may be empty.
071     * 
072     * @throws WvcmException if this proxy does not define a value for the
073     *             {@link #USER_DATABASES} property.
074     */
075    ResourceList<CqUserDb> getUserDatabases() throws WvcmException;
076    
077    /**
078     * Indicates whether the current authentication algorithm is ClearQuest
079     * first (then LDAP) or ClearQuest only (no LDAP).
080     */
081    PropertyName<AuthenticationAlgorithm> AUTHENTICATION_ALGORITHM =
082        new PropertyName<AuthenticationAlgorithm>(PROPERTY_NAMESPACE,
083                                                  "authentication-algorithm");
084
085    /**
086      * Returns the value of the {@link #AUTHENTICATION_ALGORITHM AUTHENTICATION_ALGORITHM}
087      * property as defined by this proxy.
088      * 
089      * @return The AuthenticationAlgorithm value. Will never be <b>null</b>.
090      * 
091      * @throws WvcmException if this proxy does not define a value for the
092      *             {@link #AUTHENTICATION_ALGORITHM AUTHENTICATION_ALGORITHM} property.
093      */
094     AuthenticationAlgorithm getAuthenticationAlgorithm() throws WvcmException;
095
096
097    /**
098     * Defines a new value for the
099     * {@link #AUTHENTICATION_ALGORITHM AUTHENTICATION_ALGORITHM} property of
100     * this proxy.
101     * 
102     * @param value An AuthenticationAlgorithm object specifying the new value
103     *            of the property. Must not be <b>null</b>.
104     */
105     void setAuthenticationAlgorithm(AuthenticationAlgorithm value);
106     
107    /**
108     * AuthenticationAlgorithm constants specify which authentication search
109     * strategy is selected when a Rational ClearQuest user logs on.
110     */
111     enum AuthenticationAlgorithm implements StpExEnumeration
112     {
113        /**
114         * Authenticate using traditional Rational ClearQuest user
115         * authentication as the preference, and failing that, attempt to
116         * authenticate using LDAP authentication.
117         */
118         CLEAR_QUEST_FIRST,
119         
120        /**
121         * Traditional Rational ClearQuest user authentication. Does not
122         * allow LDAP authentication. This is the default algorithm.
123         */
124         CLEAR_QUEST_ONLY;
125     }
126
127     /**
128         * Answers whether or not this database set, using the CqProvider of
129         * this proxy, provides user and group administration functions such as
130         * the creation of new users and groups and the modification of user and
131         * group properties.
132         */
133     static PropertyName<Boolean> IS_USER_ADMIN_ENABLED =
134         new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-user-admin-enabled");
135
136     /**
137         * Returns the value of the
138         * {@link #IS_USER_ADMIN_ENABLED IS_USER_ADMIN_ENABLED} property as
139         * defined by this proxy.
140         * 
141         * @return <b>true</b> if user and group administration is supported by
142         *         this database through this proxy's CqProvider; <b>false</b>
143         *         otherwise.
144         * 
145         * @throws WvcmException
146         *             if this proxy does not define a value for the
147         *             {@link #IS_USER_ADMIN_ENABLED IS_USER_ADMIN_ENABLED}
148         *             property.
149         */
150     boolean getIsUserAdminEnabled() throws WvcmException;
151
152}