PropertyClass


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.boot;
21  
22  import java.io.ByteArrayOutputStream  ;
23  import java.io.IOException  ;
24  import java.io.ObjectOutputStream  ;
25  import java.util.Collection  ;
26  
27  
28  /**
29   * Interface to be implemented by all <i>Property Classes</i>.
30   *  
31   * @author Brett Smith <a HREF="mailto: brett@3sp.com">&lt;brett@3sp.com&gt;</a>
32   */
33  public interface PropertyClass extends Comparable  <PropertyClass> {
34      /**
35       * Get the name of this property type
36       * 
37       * @return property type name
38       */
39      public String   getName();
40      
41      /**
42       * Register a new property definition.
43       * 
44       * @param propertyDefinition definition to register
45       */
46      public void registerPropertyDefinition(PropertyDefinition propertyDefinition);
47      
48      /**
49       * Deregister an existing property definition
50       * 
51       * @param propertyDefinitionName name of property definition to deregister
52       */
53      public void deregisterPropertyDefinition(String   propertyDefinitionName);
54      
55      /**
56       * Get a single registered property definition.
57       * 
58       * @param name name of property definition 
59       * @return property definition
60       */
61      public PropertyDefinition getDefinition(String   name);
62  
63      /**
64       * Get a list of all registered property definitions for this type.
65       *  
66       * @return property definitions
67       */
68      public Collection  <PropertyDefinition> getDefinitions();
69  
70      /**
71       * Get the value of a property. If the property has never been set then
72       * the default value provided in the {@link PropertyDefinition} will
73       * be returned. <code>null</code> should never be returned. 
74       *  
75       * 
76       * @param key property key
77       * @return value
78       * @throws IllegalArgumentException if property doesn't exist
79       */
80      public String   retrieveProperty(AbstractPropertyKey key) throws IllegalArgumentException  ;
81  
82  
83      /**
84       * Retrieve a property as an integer. The value will be retrieved as a string
85       * then converted to a primitive int.
86       * <p>
87       * If the property has never been set then the default value provided in the
88       * {@link PropertyDefinition} will be returned.
89       * 
90       * @param key property key
91       * @return value
92       * @throws IllegalArgumentException if property doesn't exist
93       */
94      public int retrievePropertyInt(AbstractPropertyKey key) throws IllegalArgumentException  ;
95  
96      /**
97       * Retrieve a property as a long. The value will be retrieved as a string then
98       * converted to a primitive long.
99       * <p>
100      * If the property has never been set then the default value provided in the
101      * {@link PropertyDefinition} will be returned.
102      * 
103      * @param key property key
104      * @return value
105      * @throws IllegalArgumentException if property doesn't exist
106      */
107     public long retrievePropertyLong(AbstractPropertyKey key) throws IllegalArgumentException  ;
108 
109     /**
110      * Retrieve a property as a boolen. The value will be retrieved as a string then
111      * converted to a primitive boolean, <code>true</code> if the string value
112      * is <i>true</i> otherwise <code>false</code>.
113      * <p>
114      * If the property has never been set then the default value provided in the
115      * {@link PropertyDefinition} will be returned.
116      * <p>
117      * 
118      * @param key property key
119      * @return value
120      * @throws IllegalArgumentException if property doesn't exist
121      */
122     public boolean retrievePropertyBoolean(AbstractPropertyKey key) throws IllegalArgumentException  ;
123 
124     /**
125      * Retrieve a property as a list. The value will be retrieved as a string then
126      * converted to a {@link PropertyList}.
127      * <p>
128      * If the property has never been set then the default value provided in the
129      * {@link PropertyDefinition} will be returned.
130      * 
131      * @param key property key
132      * @return value
133      * @throws IllegalArgumentException if property doesn't exist
134      */
135     public PropertyList retrievePropertyList(AbstractPropertyKey key) throws IllegalArgumentException  ;
136     
137     /**
138      * Add a new category definition. Categories may be nested so you must also
139      * provide the parent category ID of the category to add. Use <code>-1</code>
140      * to add categories to the root of the tree.
141      * 
142      * @param parentId parent category ID or -1 for root
143      * @param category category to add
144      */
145     public void addPropertyDefinitionCategory(int parentId, PropertyDefinitionCategory category);
146 
147     /**
148      * Remove a category from its parent. Use -1 to remove categories at the
149      * root of the tree.
150      * 
151      * @param parentId parent category ID or -1 for root
152      * @param category category to remove
153      */
154     public void removePropertyDefinitionCategory(int parentId, PropertyDefinitionCategory category);
155 
156     /**
157      * Get a list of all property definition categories for this property
158      * class
159      * 
160      * @return list of categories
161      */
162     public Collection  <PropertyDefinitionCategory> getCategories();
163     
164     /**
165      * Get a category definition given its ID. <code>null</code> will be 
166      * returned if no such category exists.
167      * 
168      * @param id id of category definition to retrieve 
169      * @return category definition.
170      */
171     public PropertyDefinitionCategory getPropertyDefinitionCategory(int id);
172 
173     /**
174      * Set the value of a property. <code>null</code> should never be provided.
175      * <p> 
176      * Note, if {@link #setAutoCommit(boolean)} has been set to true then
177      * the property value should not be persisted to the underlying store until
178      * the {@link #commit()} method is called. 
179      *  
180      * @param key property key
181      * @param value value
182      * @return old value
183      * @throws IllegalArgumentException if property doesn't exist
184      */
185     public String   storeProperty(AbstractPropertyKey key, String   value) throws IllegalArgumentException  ;
186     
187     /**
188      * Get if this property class supports replacement variables in its 
189      * values. If its does, the text should be expanded when used and care
190      * take never to store expanded values. 
191      * 
192      * @return supports replacement variables in values
193      */
194     public boolean isSupportsReplacementVariablesInValues();
195 
196     /**
197      * Get if the named property definition exists in this property
198      * class.
199      * 
200      * @param name property definition name
201      * @return exists
202      */
203     public boolean isDefinitionExists(String   name);
204     
205     /**
206      * Set whether the setting of property values should be persisted immediately 
207      * to the underlying store or deferred until the {@link #commit()} method is 
208      * called. 
209      * 
210      * NOTE This is NOT proper transaction support and should only be used
211      * in a single user instance of SSL-Explorer such as the installation wizard.
212      * 
213      * @param autoCommit <true>code</code> to persist properties immediately
214      */
215     public void setAutoCommit(boolean autoCommit);
216     
217     /**
218      * Commits any stored properties to the underlying store. 
219      * 
220      * @see #setAutoCommit(boolean)
221      */
222     public void commit();
223 
224     /**
225      * Remove all property definitions
226      */
227     public void clearPropertyDefinitions();
228 
229     /**
230      * Remove all property definition categories
231      */
232     public void clearPropertyDefinitionCategories();
233 
234     /**
235      * Add a collection of property definitions to this call.
236      *  
237      * @param propertyDefinitions property definitions
238      */
239     public void addPropertyDefinitions(Collection  <PropertyDefinition> propertyDefinitions);
240 
241     /**
242      * Add a collection of property definitions to this call.
243      *  
244      * @param propertyDefinitionCategories property definitions
245      */
246     public void addPropertyDefinitionCategories(Collection  <PropertyDefinitionCategory> propertyDefinitionCategories);
247     
248     /**
249      * Store all definitions and categories so they may be restored using
250      * the {@link #restore()} method. This is used to roll back and changes
251      * that may have been made to a property class during extension loading.
252      * 
253      * @throws IOException 
254      */
255     public void store() throws IOException  ;
256     
257     /**
258      * Reset any stored definitions and categories.
259      */
260     public void reset();
261     
262     /**
263      * Restore any stored definitions and categories.
264      * 
265      * @throws IOException
266      */
267     public void restore() throws IOException  ;
268 }
269
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags