Clover Coverage Report
Coverage timestamp: Sun Mar 23 2008 08:24:39 GMT
0   222   1   -
0   12   -   0
0     -  
1    
 
 
  AttributeRepository       Line # 106 0 1 - -1.0
 
No Tests
 
1    /*
2    * Copyright (c) 2000-2005, University of Salford
3    * All rights reserved.
4    *
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions are met:
7    *
8    * Redistributions of source code must retain the above copyright notice, this
9    * list of conditions and the following disclaimer.
10    *
11    * Redistributions in binary form must reproduce the above copyright notice,
12    * this list of conditions and the following disclaimer in the documentation
13    * and/or other materials provided with the distribution.
14    *
15    * Neither the name of the University of Salford nor the names of its
16    * contributors may be used to endorse or promote products derived from this
17    * software without specific prior written permission.
18    *
19    * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20    * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21    * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22    * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
23    * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24    * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25    * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26    * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27    * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28    * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29    * POSSIBILITY OF SUCH DAMAGE.
30    */
31    /*
32    * Copyright (c) 2006, University of Kent
33    * All rights reserved.
34    *
35    * Redistribution and use in source and binary forms, with or without
36    * modification, are permitted provided that the following conditions are met:
37    *
38    * Redistributions of source code must retain the above copyright notice, this
39    * list of conditions and the following disclaimer.
40    *
41    * Redistributions in binary form must reproduce the above copyright notice,
42    * this list of conditions and the following disclaimer in the documentation
43    * and/or other materials provided with the distribution.
44    *
45    * 1. Neither the name of the University of Kent nor the names of its
46    * contributors may be used to endorse or promote products derived from this
47    * software without specific prior written permission.
48    *
49    * 2. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
50    * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
51    * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
52    * PURPOSE ARE DISCLAIMED.
53    *
54    * 3. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
55    * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
56    * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
57    * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
58    * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
59    * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
60    * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
61    * POSSIBILITY OF SUCH DAMAGE.
62    *
63    * 4. YOU AGREE THAT THE EXCLUSIONS IN PARAGRAPHS 2 AND 3 ABOVE ARE REASONABLE
64    * IN THE CIRCUMSTANCES. IN PARTICULAR, YOU ACKNOWLEDGE (1) THAT THIS
65    * SOFTWARE HAS BEEN MADE AVAILABLE TO YOU FREE OF CHARGE, (2) THAT THIS
66    * SOFTWARE IS NOT "PRODUCT" QUALITY, BUT HAS BEEN PRODUCED BY A RESEARCH
67    * GROUP WHO DESIRE TO MAKE THIS SOFTWARE FREELY AVAILABLE TO PEOPLE WHO WISH
68    * TO USE IT, AND (3) THAT BECAUSE THIS SOFTWARE IS NOT OF "PRODUCT" QUALITY
69    * IT IS INEVITABLE THAT THERE WILL BE BUGS AND ERRORS, AND POSSIBLY MORE
70    * SERIOUS FAULTS, IN THIS SOFTWARE.
71    *
72    * 5. This license is governed, except to the extent that local laws
73    * necessarily apply, by the laws of England and Wales.
74    */
75   
76    package issrg.utils.repository;
77   
78    /**
79    * This interface defines the basic methods that can be performed on a read-only
80    * repository. It provides methods for retrieving attributes from a given entry
81    * (attributes and entries are terms like for the Directory). Besides this the
82    * caller can enquire on the status of the repository between calls to react
83    * more
84    * intelligently should an outage occur.
85    *
86    * <p>Note that some terms (like DN) are Directory-like, but in fact they are
87    * treated in a quite general fashion, and the interface does not require them
88    * to be DNs, if the implementation uses a different naming convention.
89    *
90    * <p>For better multi-threaded support it is advised that the methods were
91    * NOT synchronized, so that multiple threads could request attributes
92    * simultaneously. Note also that if you do need them to be synchronized, make
93    * sure that there will be no recursive invocation of it from multiple threads.
94    * For example, MultiRepository spawns multiple threads that often invoke the
95    * same MultiRepository; if somehow your repository invokes getAttributes on
96    * the same MultiRepository that called it, the synchronized method in your
97    * repository may block execution. So the remedy is: don't wrap repositories
98    * that may call you, or don't use synchronized methods.
99    *
100    * @author A Otenko
101    * @version 1.0
102    *
103    * @see MultiRepository
104    */
105   
 
106    public interface AttributeRepository {
107    /**
108    * This is a status code for when everything is alright with the repository.
109    * Particularly, the
110    * last function call succeeded.
111    */
112    public final static int SUCCESS_STATUS = 0;
113   
114    /**
115    * This is a status code for when an unrecoverable error occurred.
116    */
117    public final static int FAILURE_STATUS = 1;
118   
119    /**
120    * This is a status code for when the repository succeeded to execute the
121    * call only partially. For example, only part of attributes were returned.
122    */
123    public final static int PARTIAL_SUCCESS_STATUS = 2;
124   
125    /**
126    * This is when the repository failed to process a request because any of the
127    * previous calls returned an unfavourable result. Generally, this means that
128    * you should have checked the status before calling and calculate your
129    * decision to call this method more carefully. Repository implementations
130    * may not use this error code at all.
131    */
132    public final static int INHERENT_FAILURE_STATUS = 3;
133   
134    /**
135    * This method returns the given attribute or null, if the attribute is not
136    * present
137    * in the given entry of the repository. Does effectively the same as
138    * <p><code>getAttributes(DN, new String[]{AttributeName});</code>
139    * <p>though, returns one attribute only.
140    *
141    * @param DN is the Principal, for which to retrieve the attribute
142    * @param AttributeName is a repository attribute name of the attribute to
143    * return
144    *
145    * @return an Attribute with multiple values, retrieved from the Repository;
146    * can be null, if no such attribute exists in the given entry
147    *
148    * @throws RepositoryException, if no such entry exists, or other error occurs
149    * during the call
150    */
151    public javax.naming.directory.Attribute getAttribute(java.security.Principal DN, String AttributeName) throws RepositoryException;
152   
153    /**
154    * This method does the same as <code>getAttribute</code> for each of the
155    * specified attributes
156    * in the attribute list. It looks in the named entry for the set
157    * of attributes. It returns any of the attributes found. Some of the
158    * attributes may be missing in the entry.
159    *
160    * @param DN is the Principal, for which to retrieve the attributes
161    * @param AttributeNames is an array of repository attribute names of
162    * the attributes to
163    * return; returns all attributes available, if the array is null
164    *
165    * @return an Attributes object with multiple values for each attribute,
166    * retrieved from the Repository; can be either an empty set of attributes
167    * or null, if no such attributes exist
168    *
169    * @throws RepositoryException, if no such entry exists, or other error occurs
170    * during the call
171    */
172    public javax.naming.directory.Attributes getAttributes(java.security.Principal DN, String [] AttributeNames) throws RepositoryException;
173   
174    /**
175    * This method returns the collection of all attributes and all of their
176    * values. Does exactly the same as
177    * <p><code>getAttributes(DN, null);</code>
178    *
179    * @param DN is the Principal, for which to retrieve the attributes
180    *
181    * @return an Attributes object, containing all values of all attributes of
182    * the given Principal; can be an empty set of attributes or null, if no
183    * attributes exist
184    *
185    * @throws RepositoryException, if no such entry exists, or other error occurs
186    * during the call
187    */
188    public javax.naming.directory.Attributes getAllAttributes(java.security.Principal DN) throws RepositoryException;
189   
190   
191    /**
192    * This method returns the status of the Repository.
193    *
194    * @return one of the *_STATUS values
195    *
196    * @see #SUCCESS_STATUS
197    * @see #FAILURE_STATUS
198    * @see #PARTIAL_SUCCESS_STATUS
199    * @see #INHERENT_FAILURE_STATUS
200    */
201    public int getStatus();
202   
203    /**
204    * This method returns the last Exception thrown or an exception the
205    * Repository wanted
206    * to throw very much, but did not, only because the error was not
207    * fatal.
208    *
209    * <p><b>TODO:</b> I am very keen to remove getStatus() method, and return
210    * DiagnosisException only; which will contain the status code in it and a
211    * reference to an embedded exception. Thus it will be possible to throw such
212    * an exception in cases of need, and still it will be possible to keep it
213    * for further information. I envisage that the PbaException is one of this
214    * sort: a DiagnosisException.
215    *
216    * @return the last Throwable the Repository was eager to throw or has thrown
217    *
218    * @see #getStatus()
219    */
220    public Throwable getDiagnosis();
221    }
222