KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > schlichtherle > key > PromptingKeyProviderUI


1 /*
2  * Copyright 2006 Schlichtherle IT Services
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16
17 package de.schlichtherle.key;
18
19 /**
20  * Used by {@link PromptingKeyProvider}s for the actual prompting of the user
21  * for a key (a password for example) which is required to access a protected
22  * resource.
23  * This interface is not depending on any particular user interface techology,
24  * so prompting could be implemented using Swing, the console, a web page
25  * or any other user interface technology.
26  * <p>
27  * Implementations of this interface are instantiated and maintained by the
28  * {@link PromptingKeyManager} and are shared between different
29  * {@link PromptingKeyProvider} instances.
30  * Hence, implementations of this interface <em>must</em> be thread safe
31  * and should have no side effects!
32  *
33  * @author Christian Schlichtherle
34  * @version @version@
35  * @since TrueZIP 6.0
36  */

37 public interface PromptingKeyProviderUI {
38
39     /**
40      * Prompts the user for the key which may be used to create a new
41      * protected resource or entirely replace the contents of an already
42      * existing protected resource.
43      * <p>
44      * Upon return, the implementation is expected to update the common key
45      * in <code>provider</code>.
46      * Upon return, if <code>provider.getKey()</code> returns <code>null</code>,
47      * prompting for the key is assumed to have been cancelled by the user.
48      * In this case, the current and each subsequent call to
49      * {@link KeyProvider#getOpenKey} or {@link KeyProvider#getCreateKey}
50      * by the client results in an {@link UnknownKeyException} and the user
51      * is not prompted anymore until the provider is reset by the
52      * {@link KeyManager}.
53      * Otherwise, the key is used as the common key, a clone of which is
54      * provided to the client upon request.
55      * <p>
56      * <b>Hint:</b> If the user cancels the dialog, it is recommended to
57      * leave the provider's <code>key</code> property simply unmodified.
58      * This causes the old key to be reused and allows the client to
59      * continue its operation as if the user would not have requested to
60      * change the key.
61      * <p>
62      * Since TrueZIP 6.4, an implementation may also throw a
63      * {@link RuntimeException} with any kind of {@link UnknownKeyException}
64      * as its cause.
65      * This will trigger the calling method in the
66      * <code>PromptingKeyProvider</code> class to unwrap and pass on the
67      * cause without changing its state.
68      * This may be useful if prompting was interrupted by a call to
69      * {@link Thread#interrupt} while waiting on the Event Dispatch Thread.
70      * In this case, another try to prompt the user should have the chance to
71      * succeed instead of being cancelled without actually prompting the user
72      * again.
73      * To trigger this behaviour, the implementation should simply throw any
74      * kind of <code>RuntimeException</code> with a
75      * {@link KeyPromptingInterruptedException} as its cause.
76      *
77      * @param provider The default key provider to store the result in.
78      * @throws RuntimeException with an {@link UnknownKeyException} as its
79      * cause if the implementation does not want the key provider's
80      * state to be changed.
81      */

82     // TODO: Add UnknownKeyException to the signature of this method in TrueZIP 7.
83
void promptCreateKey(PromptingKeyProvider provider);
84
85     /**
86      * Prompts the user for the key which may be used to open an existing
87      * protected resource in order to access its contents.
88      * <p>
89      * Upon return, the implementation is expected to update the common key
90      * in <code>provider</code>.
91      * Upon return, if <code>provider.getKey()</code> returns <code>null</code>,
92      * prompting for the key is assumed to have been cancelled by the user.
93      * In this case, the current and each subsequent call to
94      * {@link KeyProvider#getOpenKey} or {@link KeyProvider#getCreateKey}
95      * by the client results in an {@link UnknownKeyException} and the user
96      * is not prompted anymore until the provider is reset by the
97      * {@link KeyManager}.
98      * Otherwise, the key is used as the common key, a clone of which is
99      * provided to the client upon request.
100      * <p>
101      * Since TrueZIP 6.4, an implementation may also throw a
102      * {@link RuntimeException} with any kind of {@link UnknownKeyException}
103      * as its cause.
104      * This will trigger the calling method in the
105      * <code>PromptingKeyProvider</code> class to unwrap and pass on the
106      * cause without changing its state.
107      * This may be useful if prompting was interrupted by a call to
108      * {@link Thread#interrupt} while waiting on the Event Dispatch Thread.
109      * In this case, another try to prompt the user should have the chance to
110      * succeed instead of being cancelled without actually prompting the user
111      * again.
112      * To trigger this behaviour, the implementation should simply throw any
113      * kind of <code>RuntimeException</code> with a
114      * {@link KeyPromptingInterruptedException} as its cause.
115      *
116      * @param provider The key provider to store the result in.
117      * @return <code>true</code> if the user has requested to change the
118      * provided key.
119      * @throws RuntimeException with an {@link UnknownKeyException} as its
120      * cause if the implementation does not want the key provider's
121      * state to be changed.
122      */

123     // TODO: Add UnknownKeyException to the signature of this method in TrueZIP 7.
124
boolean promptUnknownOpenKey(PromptingKeyProvider provider);
125
126     /**
127      * Prompts the user for the key which may be used to open an existing
128      * protected resource in order to access its contents.
129      * This is called if the key returned by a previous call to
130      * {@link #promptUnknownOpenKey} is invalid.
131      * <p>
132      * Upon return, the implementation is expected to update the common key
133      * in <code>provider</code>.
134      * Upon return, if <code>provider.getKey()</code> returns <code>null</code>,
135      * prompting for the key is assumed to have been cancelled by the user.
136      * In this case, the current and each subsequent call to
137      * {@link KeyProvider#getOpenKey} or {@link KeyProvider#getCreateKey}
138      * by the client results in an {@link UnknownKeyException} and the user
139      * is not prompted anymore until the provider is reset by the
140      * {@link KeyManager}.
141      * Otherwise, the key is used as the common key, a clone of which is
142      * provided to the client upon request.
143      * <p>
144      * Since TrueZIP 6.4, an implementation may also throw a
145      * {@link RuntimeException} with any kind of {@link UnknownKeyException}
146      * as its cause.
147      * This will trigger the calling method in the
148      * <code>PromptingKeyProvider</code> class to unwrap and pass on the
149      * cause without changing its state.
150      * This may be useful if prompting was interrupted by a call to
151      * {@link Thread#interrupt} while waiting on the Event Dispatch Thread.
152      * In this case, another try to prompt the user should have the chance to
153      * succeed instead of being cancelled without actually prompting the user
154      * again.
155      * To trigger this behaviour, the implementation should simply throw any
156      * kind of <code>RuntimeException</code> with a
157      * {@link KeyPromptingInterruptedException} as its cause.
158      *
159      * @param provider The key provider to store the result in.
160      * @return <code>true</code> if the user has requested to change the
161      * provided key.
162      * @throws RuntimeException with an {@link UnknownKeyException} as its
163      * cause if the implementation does not want the key provider's
164      * state to be changed.
165      */

166     // TODO: Add UnknownKeyException to the signature of this method in TrueZIP 7.
167
boolean promptInvalidOpenKey(PromptingKeyProvider provider);
168 }
169
Popular Tags