KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sslexplorer > properties > 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 JavaDoc;
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 JavaDoc<PropertyProfile> getPropertyProfiles(String JavaDoc username, boolean includeGlobal, int realm) throws Exception JavaDoc;
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 JavaDoc retrieveGenericProperty(String JavaDoc key1, String JavaDoc key2, String JavaDoc key3, String JavaDoc key4, String JavaDoc key5) throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc key1, String JavaDoc key2, String JavaDoc key3, String JavaDoc key4, String JavaDoc key5, String JavaDoc value) throws Exception JavaDoc;
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 JavaDoc username, String JavaDoc shortName, String JavaDoc description, int baseOn, int realm)
181                     throws Exception JavaDoc;
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 JavaDoc shortName, String JavaDoc description) throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc username, String JavaDoc name, int realm) throws Exception JavaDoc;
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 JavaDoc value) throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc propertyClassName, String JavaDoc definitionName) throws Exception JavaDoc;
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 JavaDoc retrieveAttributeValue(AbstractAttributeKey attrKey) throws Exception JavaDoc;
263
264 }
Popular Tags