1 /*
2 * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.awt.datatransfer;
27
28 import java.awt.EventQueue;
29
30 import java.util.Set;
31 import java.util.HashSet;
32 import java.util.Arrays;
33
34 import java.io.IOException;
35
36 import sun.awt.EventListenerAggregate;
37
38 /**
39 * A class that implements a mechanism to transfer data using
40 * cut/copy/paste operations.
41 * <p>
42 * {@link FlavorListener}s may be registered on an instance of the
43 * Clipboard class to be notified about changes to the set of
44 * {@link DataFlavor}s available on this clipboard (see
45 * {@link #addFlavorListener}).
46 *
47 * @see java.awt.Toolkit#getSystemClipboard
48 * @see java.awt.Toolkit#getSystemSelection
49 *
50 * @author Amy Fowler
51 * @author Alexander Gerasimov
52 */
53 public class Clipboard {
54
55 String name;
56
57 /**
58 * The owner of the clipboard.
59 */
60 protected ClipboardOwner owner;
61 /**
62 * Contents of the clipboard.
63 */
64 protected Transferable contents;
65
66 /**
67 * An aggregate of flavor listeners registered on this local clipboard.
68 *
69 * @since 1.5
70 */
71 private EventListenerAggregate flavorListeners;
72
73 /**
74 * A set of <code>DataFlavor</code>s that is available on
75 * this local clipboard. It is used for tracking changes
76 * of <code>DataFlavor</code>s available on this clipboard.
77 *
78 * @since 1.5
79 */
80 private Set<DataFlavor> currentDataFlavors;
81
82 /**
83 * Creates a clipboard object.
84 * @param name for the clipboard
85 * @see java.awt.Toolkit#getSystemClipboard
86 */
87 public Clipboard(String name) {
88 this.name = name;
89 }
90
91 /**
92 * Returns the name of this clipboard object.
93 * @return the name of this clipboard object
94 *
95 * @see java.awt.Toolkit#getSystemClipboard
96 */
97 public String getName() {
98 return name;
99 }
100
101 /**
102 * Sets the current contents of the clipboard to the specified
103 * transferable object and registers the specified clipboard owner
104 * as the owner of the new contents.
105 * <p>
106 * If there is an existing owner different from the argument
107 * <code>owner</code>, that owner is notified that it no longer
108 * holds ownership of the clipboard contents via an invocation
109 * of <code>ClipboardOwner.lostOwnership()</code> on that owner.
110 * An implementation of <code>setContents()</code> is free not
111 * to invoke <code>lostOwnership()</code> directly from this method.
112 * For example, <code>lostOwnership()</code> may be invoked later on
113 * a different thread. The same applies to <code>FlavorListener</code>s
114 * registered on this clipboard.
115 * <p>
116 * The method throws <code>IllegalStateException</code> if the clipboard
117 * is currently unavailable. For example, on some platforms, the system
118 * clipboard is unavailable while it is accessed by another application.
119 *
120 * @param contents the transferable object representing the
121 * clipboard content
122 * @param owner the object which owns the clipboard content
123 * @throws IllegalStateException if the clipboard is currently unavailable
124 * @see java.awt.Toolkit#getSystemClipboard
125 */
126 public synchronized void setContents(Transferable contents, ClipboardOwner owner) {
127 final ClipboardOwner oldOwner = this.owner;
128 final Transferable oldContents = this.contents;
129
130 this.owner = owner;
131 this.contents = contents;
132
133 if (oldOwner != null && oldOwner != owner) {
134 EventQueue.invokeLater(new Runnable() {
135 public void run() {
136 oldOwner.lostOwnership(Clipboard.this, oldContents);
137 }
138 });
139 }
140 fireFlavorsChanged();
141 }
142
143 /**
144 * Returns a transferable object representing the current contents
145 * of the clipboard. If the clipboard currently has no contents,
146 * it returns <code>null</code>. The parameter Object requestor is
147 * not currently used. The method throws
148 * <code>IllegalStateException</code> if the clipboard is currently
149 * unavailable. For example, on some platforms, the system clipboard is
150 * unavailable while it is accessed by another application.
151 *
152 * @param requestor the object requesting the clip data (not used)
153 * @return the current transferable object on the clipboard
154 * @throws IllegalStateException if the clipboard is currently unavailable
155 * @see java.awt.Toolkit#getSystemClipboard
156 */
157 public synchronized Transferable getContents(Object requestor) {
158 return contents;
159 }
160
161
162 /**
163 * Returns an array of <code>DataFlavor</code>s in which the current
164 * contents of this clipboard can be provided. If there are no
165 * <code>DataFlavor</code>s available, this method returns a zero-length
166 * array.
167 *
168 * @return an array of <code>DataFlavor</code>s in which the current
169 * contents of this clipboard can be provided
170 *
171 * @throws IllegalStateException if this clipboard is currently unavailable
172 *
173 * @since 1.5
174 */
175 public DataFlavor[] getAvailableDataFlavors() {
176 Transferable cntnts = getContents(null);
177 if (cntnts == null) {
178 return new DataFlavor[0];
179 }
180 return cntnts.getTransferDataFlavors();
181 }
182
183 /**
184 * Returns whether or not the current contents of this clipboard can be
185 * provided in the specified <code>DataFlavor</code>.
186 *
187 * @param flavor the requested <code>DataFlavor</code> for the contents
188 *
189 * @return <code>true</code> if the current contents of this clipboard
190 * can be provided in the specified <code>DataFlavor</code>;
191 * <code>false</code> otherwise
192 *
193 * @throws NullPointerException if <code>flavor</code> is <code>null</code>
194 * @throws IllegalStateException if this clipboard is currently unavailable
195 *
196 * @since 1.5
197 */
198 public boolean isDataFlavorAvailable(DataFlavor flavor) {
199 if (flavor == null) {
200 throw new NullPointerException("flavor");
201 }
202
203 Transferable cntnts = getContents(null);
204 if (cntnts == null) {
205 return false;
206 }
207 return cntnts.isDataFlavorSupported(flavor);
208 }
209
210 /**
211 * Returns an object representing the current contents of this clipboard
212 * in the specified <code>DataFlavor</code>.
213 * The class of the object returned is defined by the representation
214 * class of <code>flavor</code>.
215 *
216 * @param flavor the requested <code>DataFlavor</code> for the contents
217 *
218 * @return an object representing the current contents of this clipboard
219 * in the specified <code>DataFlavor</code>
220 *
221 * @throws NullPointerException if <code>flavor</code> is <code>null</code>
222 * @throws IllegalStateException if this clipboard is currently unavailable
223 * @throws UnsupportedFlavorException if the requested <code>DataFlavor</code>
224 * is not available
225 * @throws IOException if the data in the requested <code>DataFlavor</code>
226 * can not be retrieved
227 *
228 * @see DataFlavor#getRepresentationClass
229 *
230 * @since 1.5
231 */
232 public Object getData(DataFlavor flavor)
233 throws UnsupportedFlavorException, IOException {
234 if (flavor == null) {
235 throw new NullPointerException("flavor");
236 }
237
238 Transferable cntnts = getContents(null);
239 if (cntnts == null) {
240 throw new UnsupportedFlavorException(flavor);
241 }
242 return cntnts.getTransferData(flavor);
243 }
244
245
246 /**
247 * Registers the specified <code>FlavorListener</code> to receive
248 * <code>FlavorEvent</code>s from this clipboard.
249 * If <code>listener</code> is <code>null</code>, no exception
250 * is thrown and no action is performed.
251 *
252 * @param listener the listener to be added
253 *
254 * @see #removeFlavorListener
255 * @see #getFlavorListeners
256 * @see FlavorListener
257 * @see FlavorEvent
258 * @since 1.5
259 */
260 public synchronized void addFlavorListener(FlavorListener listener) {
261 if (listener == null) {
262 return;
263 }
264 if (flavorListeners == null) {
265 currentDataFlavors = getAvailableDataFlavorSet();
266 flavorListeners = new EventListenerAggregate(FlavorListener.class);
267 }
268 flavorListeners.add(listener);
269 }
270
271 /**
272 * Removes the specified <code>FlavorListener</code> so that it no longer
273 * receives <code>FlavorEvent</code>s from this <code>Clipboard</code>.
274 * This method performs no function, nor does it throw an exception, if
275 * the listener specified by the argument was not previously added to this
276 * <code>Clipboard</code>.
277 * If <code>listener</code> is <code>null</code>, no exception
278 * is thrown and no action is performed.
279 *
280 * @param listener the listener to be removed
281 *
282 * @see #addFlavorListener
283 * @see #getFlavorListeners
284 * @see FlavorListener
285 * @see FlavorEvent
286 * @since 1.5
287 */
288 public synchronized void removeFlavorListener(FlavorListener listener) {
289 if (listener == null || flavorListeners == null) {
290 return;
291 }
292 flavorListeners.remove(listener);
293 }
294
295 /**
296 * Returns an array of all the <code>FlavorListener</code>s currently
297 * registered on this <code>Clipboard</code>.
298 *
299 * @return all of this clipboard's <code>FlavorListener</code>s or an empty
300 * array if no listeners are currently registered
301 * @see #addFlavorListener
302 * @see #removeFlavorListener
303 * @see FlavorListener
304 * @see FlavorEvent
305 * @since 1.5
306 */
307 public synchronized FlavorListener[] getFlavorListeners() {
308 return flavorListeners == null ? new FlavorListener[0] :
309 (FlavorListener[])flavorListeners.getListenersCopy();
310 }
311
312 /**
313 * Checks change of the <code>DataFlavor</code>s and, if necessary,
314 * notifies all listeners that have registered interest for notification
315 * on <code>FlavorEvent</code>s.
316 *
317 * @since 1.5
318 */
319 private void fireFlavorsChanged() {
320 if (flavorListeners == null) {
321 return;
322 }
323 Set<DataFlavor> prevDataFlavors = currentDataFlavors;
324 currentDataFlavors = getAvailableDataFlavorSet();
325 if (prevDataFlavors.equals(currentDataFlavors)) {
326 return;
327 }
328 FlavorListener[] flavorListenerArray =
329 (FlavorListener[])flavorListeners.getListenersInternal();
330 for (int i = 0; i < flavorListenerArray.length; i++) {
331 final FlavorListener listener = flavorListenerArray[i];
332 EventQueue.invokeLater(new Runnable() {
333 public void run() {
334 listener.flavorsChanged(new FlavorEvent(Clipboard.this));
335 }
336 });
337 }
338 }
339
340 /**
341 * Returns a set of <code>DataFlavor</code>s currently available
342 * on this clipboard.
343 *
344 * @return a set of <code>DataFlavor</code>s currently available
345 * on this clipboard
346 *
347 * @since 1.5
348 */
349 private Set<DataFlavor> getAvailableDataFlavorSet() {
350 Set<DataFlavor> set = new HashSet<>();
351 Transferable contents = getContents(null);
352 if (contents != null) {
353 DataFlavor[] flavors = contents.getTransferDataFlavors();
354 if (flavors != null) {
355 set.addAll(Arrays.asList(flavors));
356 }
357 }
358 return set;
359 }
360 }