propertydatabase.java

这是linux下ssl vpn的实现程序

/*
 *  SSL-Explorer
 *
 *  Copyright (C) 2003-2006 3SP LTD. All Rights Reserved
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  as published by the Free Software Foundation; either version 2 of
 *  the License, or (at your option) any later version.
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public
 *  License along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
			
package com.sslexplorer.properties;

import java.util.List;

import com.sslexplorer.boot.PropertyDefinition;
import com.sslexplorer.core.Database;
import com.sslexplorer.security.SessionInfo;

/**
 * <p>
 * Property databases are a core component of SSL-Explorer and are used to store 
 * property definitions, property profiles, property categories and property values.
 * <p>
 * The properties store system wide configuration information, global user
 * configuration and users personal configuration.
 * <p>
 * Many of these methods will be called a <b>lot</b>.  If the storage mechanism
 * for the implementation is slow, you would be advised to maintain some 
 * kind of cache.   
 * 
 * <h3>Property Definitions</h3>
 * 
 * Each property that this database may store is keyed by its <i>id</i>. For
 * each unique <i>id</i> there must have been a single {@link com.sslexplorer.boot.PropertyDefinition}
 * registered with this database using {@link #registerPropertyDefinition(PropertyDefinition)}
 * <p>
 * Each definition contains information about the value that will be stored
 * against it. This includes the type of value (string, integer, boolean etc),
 * the bundle in which the human readable name and description is held,
 * its category ID and other information. See {@link com.sslexplorer.boot.PropertyDefinition}
 * for more information.
 * 
 *  <h3>Property Categories</h3>
 *  
 *  Each property definition exists under a single category. Categories are
 *  referenced by their <i>id</i> (an integer) and must be registered with
 *  this database using {@link #addPropertyDefinitionCategory(int, PropertyDefinitionCategory)}.
 *  This method also allows categories to be nested within one another by
 *  providing the parent category. Use -1 for a root category.
 *  
 *  <h3>Property Profiles and Values</h3>
 *  
 *  All property values are held in a profile. Profiles provide a way of 
 *  of the user selecting a set of property values depending on the environment
 *  they are in. For example, there may be a profile configured whose properties
 *  are appropriate for using when a user is connecting via the Office Lan. 
 *  The administrator may also have configured a second profile who property 
 *  values are more appropriate when users are connecting from somewhere less
 *  secure, such as an Internet Cafe.
 *  <p>
 *  There are two types of profile, <b>Global</b>, and <b>Personal</b>.  
 *  Global profiles are created by an administrator and then assigned to
 *  users via policies. Many users may share the same profile. Personal profiles
 *  are created by users themselves and are only usable by them. 
 *  <p>
 *  Only property definitions that have a visibility of {@link com.sslexplorer.boot.PropertyDefinition#PROFILE}
 *  may exist in global or personal profiles.  
 *  <p>
 *  There also exists a special <b>Default</b> global profile. This profile has an
 *  id of 0 and is also used to the default global profile <strong>and</strong>
 *  system configuration <strong>and</strong> hidden properties. 
 *  
 *  <h3>Context Configuration Properties</h3>
 *  
 *  Properties that are only used for configuring the {@link com.sslexplorer.boot.Context}
 *  implementation in use. Properties of this type are different in that their
 *  values are stored and retrieved using {@link com.sslexplorer.boot.Context#setContextProperty(String, String)}
 *  and {@link com.sslexplorer.boot.Context#getContextProperty(String)}. The 
 *  property definition objects are retrieve using {@link com.sslexplorer.boot.Context#getContextPropertyDefinitions()}
 *  (these are cached at start up).
 *  
 *  <h3>System Configuration Properties</h3>
 *  
 *  System configuration properties do not effect users directly. 
 *  Such property definitions have a visibility of 
 *  {@link com.sslexplorer.boot.PropertyDefinition#SYSTEM_CONFIGURATION}
 *  
 *  <h3>Hidden Properties</h3>
 *  
 *  Hidden configuration properties do not effect users directly and are used
 *  internally. Such property definitions will return true when 
 *  {@link com.sslexplorer.boot.PropertyDefinition#isHidden()} is called.
 *   
 * 
 * @author Brett Smith <a href="mailto: [e-mail]">&lt;[e-mail]&gt;</a>
 * @version $Revision: 1.1 $
 */

public interface PropertyDatabase extends Database {
    
    /**
     * Get a list of all registered {@link PropertyDefinition} objects depending
     * on the specified <i>Scope</i>.
     * <p>
     * If a scope of {@link com.sslexplorer.security.Constants#SCOPE_PERSONAL} 
     * or {@link com.sslexplorer.security.Constants#SCOPE_GLOBAL} 
     * is provided, all property definitions that have a visibility of 
     * {@link PropertyDefinition#PROFILE} are returned.
     * <p>
     * If a scope of {@link com.sslexplorer.security.Constants#SCOPE_SETUP} 
     * is provided, all property definitions that have a visibility of 
     * {@link PropertyDefinition#SYSTEM_CONFIGURATION} and
     * {@link PropertyDefinition#CONTEXT_CONFIGURATION} are returned.
     * <p>
     * This may seem a little odd. Why not just provide the visiblity 
     * required? Its just a hang-up from SSL-Explorer pre 0.2.0 and will
     * likely change. 
     * 
     * @param scope scope to list.
     * @return list of property definitions
     * @throws Exception
     */
    public List getPropertyDefinitions(String scope) throws Exception;

    /**
     * Get a list of all property profiles. If <i>username</i> is <code>null</code>
     * then global profiles are returned. If <i>username</i> is not <code>null</code>
     * then all profiles for the specfied user are returned (in this case, if
     * <i>includeGlobal</i> is <code>true</code> then all global profiles will
     * also be added to the list).
     * 
     * @param username user or <code>null</code> for global profiles
     * @param includeGlobal include global profiles.
     * @return list of property profiles
     * @throws Exception
     */
    public List getPropertyProfiles(String username, boolean includeGlobal) throws Exception;

    /**
     * Get the value of a property. If the property has never been set then
     * the default value provided in the {@link PropertyDefinition} will
     * be returned. <code>null</code> should never be returned. 
     * <p>
     * Note, It is up to the implementation to test if the property definition
     * for the provided name is of type {@link PropertyDefinition#CONTEXT_CONFIGURATION}.
     * If it is then the value should be retrieved from the context using
     * {@link com.sslexplorer.boot.Context#getContextProperty(String)}. 
     *  
     * 
     * @param profile profile id or 0 for default profile, system configuration, context or hidden property 
     * @param username username for personal profiles or <code>null</code> for a global profile / system 
     * @param name name (id) of property
     * @return value
     * @throws Exception on any error
     */
    public String getProperty(int profile, String username, String name) throws Exception;

    /**
     * Get the {@link PropertyDefinition} for the property name (id) supplied.
     * <code>null</code> will be returned if no such property definition 
     * exists.
     * 
     * @param name property name