PropertyDatabase


1   /*
2    *  SSL-Explorer
3    *
4    *  Copyright (C) 2003-2006 3SP LTD. All Rights Reserved
5    *
6    *  This program is free software; you can redistribute it and/or
7    *  modify it under the terms of the GNU General Public License
8    *  as published by the Free Software Foundation; either version 2 of
9    *  the License, or (at your option) any later version.
10   *  This program is distributed in the hope that it will be useful,
11   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   *  GNU General Public License for more details.
14   *
15   *  You should have received a copy of the GNU General Public
16   *  License along with this program; if not, write to the Free Software
17   *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18   */
19              
20  package com.sslexplorer.properties;
21  
22  import java.util.List  ;
23  
24  import com.sslexplorer.boot.PropertyDefinition;
25  import com.sslexplorer.core.Database;
26  import com.sslexplorer.properties.attributes.AbstractAttributeKey;
27  import com.sslexplorer.properties.attributes.AttributeDefinition;
28  
29  /**
30   * <p>
31   * Property databases are a core component of SSL-Explorer and are used to store 
32   * property definitions, property profiles, property categories and property values.
33   * <p>
34   * The properties store system wide configuration information, global user
35   * configuration and users personal configuration.
36   * <p>
37   * Many of these methods will be called a <b>lot</b>.  If the storage mechanism
38   * for the implementation is slow, you would be advised to maintain some 
39   * kind of cache.   
40   * 
41   * <h3>Property Definitions</h3>
42   * 
43   * Each property that this database may store is keyed by its <i>id</i>. For
44   * each unique <i>id</i> there must have been a single {@link com.sslexplorer.boot.PropertyDefinition}
45   * registered with this database using {@link #registerPropertyDefinition(PropertyDefinition)}
46   * <p>
47   * Each definition contains information about the value that will be stored
48   * against it. This includes the type of value (string, integer, boolean etc),
49   * the bundle in which the human readable name and description is held,
50   * its category ID and other information. See {@link com.sslexplorer.boot.PropertyDefinition}
51   * for more information.
52   * 
53   *  <h3>Property Categories</h3>
54   *  
55   *  Each property definition exists under a single category. Categories are
56   *  referenced by their <i>id</i> (an integer) and must be registered with
57   *  this database using {@link #addPropertyDefinitionCategory(int, PropertyDefinitionCategory)}.
58   *  This method also allows categories to be nested within one another by
59   *  providing the parent category. Use -1 for a root category.
60   *  
61   *  <h3>Property Profiles and Values</h3>
62   *  
63   *  All property values are held in a profile. Profiles provide a way of 
64   *  of the user selecting a set of property values depending on the environment
65   *  they are in. For example, there may be a profile configured whose properties
66   *  are appropriate for using when a user is connecting via the Office Lan. 
67   *  The administrator may also have configured a second profile who property 
68   *  values are more appropriate when users are connecting from somewhere less
69   *  secure, such as an Internet Cafe.
70   *  <p>
71   *  There are two types of profile, <b>Global</b>, and <b>Personal</b>.  
72   *  Global profiles are created by an administrator and then assigned to
73   *  users via policies. Many users may share the same profile. Personal profiles
74   *  are created by users themselves and are only usable by them. 
75   *  <p>
76   *  Only property definitions that have a visibility of {@link com.sslexplorer.boot.PropertyDefinition#PROFILE}
77   *  may exist in global or personal profiles.  
78   *  <p>
79   *  There also exists a special <b>Default</b> global profile. This profile has an
80   *  id of 0 and is also used to the default global profile <strong>and</strong>
81   *  system configuration <strong>and</strong> hidden properties. 
82   *  
83   *  <h3>Context Configuration Properties</h3>
84   *  
85   *  Properties that are only used for configuring the {@link com.sslexplorer.boot.Context}
86   *  implementation in use. Properties of this type are different in that their
87   *  values are stored and retrieved using {@link com.sslexplorer.boot.Context#setContextProperty(String, String)}
88   *  and {@link com.sslexplorer.boot.Context#getContextProperty(String)}. The 
89   *  property definition objects are retrieve using {@link com.sslexplorer.boot.Context#getContextPropertyDefinitions()}
90   *  (these are cached at start up).
91   *  
92   *  <h3>System Configuration Properties</h3>
93   *  
94   *  System configuration properties do not effect users directly. 
95   *  Such property definitions have a visibility of 
96   *  {@link com.sslexplorer.boot.PropertyDefinition#SYSTEM_CONFIGURATION}
97   *  
98   *  <h3>Hidden Properties</h3>
99   *  
100  *  Hidden configuration properties do not effect users directly and are used
101  *  internally. Such property definitions will return true when 
102  *  {@link com.sslexplorer.boot.PropertyDefinition#isHidden()} is called.
103  *   
104  * 
105  * @author Brett Smith <a HREF="mailto: brett@3sp.com">&lt;brett@3sp.com&gt;</a>
106  */
107 
108 public interface PropertyDatabase extends Database {
109 
110     /**
111      * Get a list of all property profiles. If <i>username</i> is <code>null</code>
112      * then global profiles are returned. If <i>username</i> is not <code>null</code>
113      * then all profiles for the specfied user are returned (in this case, if
114      * <i>includeGlobal</i> is <code>true</code> then all global profiles will
115      * also be added to the list).
116      * 
117      * @param username user or <code>null</code> for global profiles
118      * @param includeGlobal include global profiles.
119      * @param realm ID of the realm it is in.
120      * @return List<PropertyProfile> of property profiles
121      * @throws Exception
122      */
123     public List  <PropertyProfile> getPropertyProfiles(String   username, boolean includeGlobal, int realm) throws Exception  ;
124 
125     /**
126      * Get the value of a generic property. If the property has never been set 
127      * <code>null</code> will be returned.  
128      * <p>
129      * Note, this method should never be called directly, to get a property
130      * use methods in {@link com.sslexplorer.properties.Property}.
131      * 
132      * @param key1 key 1
133      * @param key2 key 2
134      * @param key3 key 3
135      * @param key4 key 4
136      * @param key5 key 5
137      * @return value
138      * @throws Exception on any error
139      */
140     public String   retrieveGenericProperty(String   key1, String   key2, String   key3, String   key4, String   key5) throws Exception  ;
141 
142     /**
143      * Get a property profile given its ID. <code>null</code> will be returned
144      * if no such property profile exists.
145      * 
146      * @param id id
147      * @return property profile
148      * @throws Exception
149      */
150     public PropertyProfile getPropertyProfile(int id) throws Exception  ;
151 
152     /**
153      * Set the value of a generic property. 
154      * <p>
155      * Note, this method should never be called directly, to set a property
156      * use methods in {@link com.sslexplorer.properties.Property} 
157      * as this also fires events.
158      * 
159      * @param key1 key 1 
160      * @param key2 key 2
161      * @param key3 key 3
162      * @param key4 key 4
163      * @param key5 key 5
164      * @param value value to set
165      * @throws Exception if property cannot be set
166      */
167     public void storeGenericProperty(String   key1, String   key2, String   key3, String   key4, String   key5, String   value) throws Exception  ;
168 
169     /**
170      * Create a new property profile given its basic details
171      * 
172      * @param username username under which to create the property profile or <code>null</code> for default profiles.
173      * @param shortName short name for the profile
174      * @param description a description of the profile
175      * @param baseOn ID of profile to base values on
176      * @param realm th ID of the realm the property is in. 
177      * @return created property profile object
178      * @throws Exception if profile cannot be created
179      */
180     public PropertyProfile createPropertyProfile(String   username, String   shortName, String   description, int baseOn, int realm)
181                     throws Exception  ;
182 
183     /**
184      * Update the basic details of a property profile
185      * 
186      * @param id id of profile
187      * @param shortName short name
188      * @param description description
189      * @throws Exception if profile cannot be updated
190      */
191     public void updatePropertyProfile(int id, String   shortName, String   description) throws Exception  ;
192 
193     /**
194      * Delete a property profile given its ID
195      * 
196      * @param id id of property profile to delete
197      * @return deleted profile 
198      * @throws Exception if profile cannot be deleted
199      */
200     public PropertyProfile deletePropertyProfile(int id) throws Exception  ;
201 
202     /**
203      * Get a property profile given a username and short name. Profiles should
204      * have unique names withing their scope (global / user) and this method
205      * is used to check whether a profile of the same name already exists. 
206      * <p>
207      * <code>null</code> will be returned if no such profile exists.
208      * 
209      * @param username username or <code>null</code> for global profiles
210      * @param name name of profilke
211      * @param realm ID for the realm it is in.
212      * @return property profile or <code>null</code> if it does not exist.
213      * @throws Exception if profile cannot be retrieved
214      */
215     public PropertyProfile getPropertyProfile(String   username, String   name, int realm) throws Exception  ;
216 
217     
218     /**
219      * Set  an attribute. Implementations <strong>must</strong>
220      * support the storing of attributes even if they are read-only.
221      * <code>null</code> should be used to unset (or remove) the attribute
222      * 
223      * @param key
224      * @param value
225      * @throws Exception on any error
226      */
227     public void storeAttributeValue(AbstractAttributeKey key, String   value) throws  Exception  ;
228     
229     /**
230      * Store a new attribute definition. 
231      *
232      * @param definition definition to store
233      * @throws Exception on any error
234      */
235     public void createAttributeDefinition(AttributeDefinition definition) throws Exception  ;
236     
237     /**
238      * Update an existing attribute definition.
239      *
240      * @param definition definition to update
241      * @throws Exception on any error
242      */
243     public void updateAttributeDefinition(AttributeDefinition definition) throws Exception  ;
244     
245     /**
246      * Delete an existing attribute definition.
247      *
248      * @param propertyClassName property class name
249      * @param definitionName definition name to delete
250      * @throws Exception on any error
251      */
252     public void deleteAttributeDefinition(String   propertyClassName, String   definitionName) throws Exception  ;
253 
254     /**
255      * Retrieve the value of the attribute. <code>null</code> should be 
256      * returned if the attribute isn't set.
257      * 
258      * @param attrKey attribute key 
259      * @return attribute value
260      * @throws Exception if attribute cannot be retrieved
261      */
262     public String   retrieveAttributeValue(AbstractAttributeKey attrKey) throws Exception  ;
263 
264 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags