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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags