1/*
2 * Copyright (c) 2014, 2017, 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
26package sun.datatransfer;
27
28import java.awt.datatransfer.DataFlavor;
29import java.awt.datatransfer.FlavorMap;
30import java.util.LinkedHashSet;
31import java.util.function.Supplier;
32
33/**
34 * Contains services which desktop provides to the datatransfer system to enrich
35 * it's functionality.
36 *
37 * @author Petr Pchelko
38 * @since 9
39 */
40public interface DesktopDatatransferService {
41
42    /**
43     * If desktop is present - invokes a {@code Runnable} on the event dispatch
44     * thread. Otherwise invokes a {@code run()} method directly.
45     *
46     * @param  r a {@code Runnable} to invoke
47     */
48    void invokeOnEventThread(Runnable r);
49
50    /**
51     * Get a platform-dependent default unicode encoding to use in datatransfer
52     * system.
53     *
54     * @return default unicode encoding
55     */
56    String getDefaultUnicodeEncoding();
57
58    /**
59     * Takes an appropriate {@code FlavorMap} from the desktop. If no
60     * appropriate table is found - uses a provided supplier to instantiate a
61     * table. If the desktop is absent - creates and returns a system singleton.
62     *
63     * @param  supplier a constructor that should be used to create a new
64     *         instance of the {@code FlavorMap}
65     * @return a {@code FlavorMap}
66     */
67    FlavorMap getFlavorMap(Supplier<FlavorMap> supplier);
68
69    /**
70     * Checks if desktop is present.
71     *
72     * @return {@code true} is the desktop is present
73     */
74    boolean isDesktopPresent();
75
76    /**
77     * Returns platform-specific mappings for the specified native format. If
78     * there are no platform-specific mappings for this native, the method
79     * returns an empty {@code Set}.
80     *
81     * @param  nat a native format to return flavors for
82     * @return set of platform-specific mappings for a native format
83     */
84    LinkedHashSet<DataFlavor> getPlatformMappingsForNative(String nat);
85
86    /**
87     * Returns platform-specific mappings for the specified flavor. If there are
88     * no platform-specific mappings for this flavor, the method returns an
89     * empty {@code Set}.
90     *
91     * @param  df {@code DataFlavor} to return mappings for
92     * @return set of platform-specific mappings for a {@code DataFlavor}
93     */
94    LinkedHashSet<String> getPlatformMappingsForFlavor(DataFlavor df);
95
96    /**
97     * This method is called for text flavor mappings established while parsing
98     * the default flavor mappings file. It stores the "eoln" and "terminators"
99     * parameters which are not officially part of the MIME type. They are MIME
100     * parameters specific to the flavormap.properties file format.
101     */
102    void registerTextFlavorProperties(String nat, String charset,
103                                      String eoln, String terminators);
104}
105