1 /*
2 * Copyright (c) 2000, 2020, 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 javax.print;
27
28 /**
29 * Services may optionally provide UIs which allow different styles of
30 * interaction in different roles. One role may be end-user browsing and setting
31 * of print options. Another role may be administering the print service.
32 * <p>
33 * Although the Print Service API does not presently provide standardised
34 * support for administering a print service, monitoring of the print service is
35 * possible and a UI may provide for private update mechanisms.
36 * <p>
37 * The basic design intent is to allow applications to lazily locate and
38 * initialize services only when needed without any API dependencies except in
39 * an environment in which they are used.
40 * <p>
41 * Swing UIs are preferred as they provide a more consistent {@literal L&F} and
42 * can support accessibility APIs.
43 * <p>
44 * Example usage:
45 * <pre>
46 * ServiceUIFactory factory = printService.getServiceUIFactory();
47 * if (factory != null) {
48 * JComponent swingui = (JComponent)factory.getUI(
49 * ServiceUIFactory.MAIN_UIROLE,
50 * ServiceUIFactory.JCOMPONENT_UI);
51 * if (swingui != null) {
52 * tabbedpane.add("Custom UI", swingui);
53 * }
54 * }
55 * </pre>
56 */
57 public abstract class ServiceUIFactory {
58
59 /**
60 * Constructor for subclasses to call.
61 */
62 protected ServiceUIFactory() {}
63
64 /**
65 * Denotes a UI implemented as a Swing component. The value of the string is
66 * the fully qualified classname : "javax.swing.JComponent".
67 */
68 public static final String JCOMPONENT_UI = "javax.swing.JComponent";
69
70 /**
71 * Denotes a UI implemented as an AWT panel. The value of the string is the
72 * fully qualified classname : "java.awt.Panel"
73 */
74 public static final String PANEL_UI = "java.awt.Panel";
75
76 /**
77 * Denotes a UI implemented as an AWT dialog. The value of the string is the
78 * fully qualified classname : "java.awt.Dialog"
79 */
80 public static final String DIALOG_UI = "java.awt.Dialog";
81
82 /**
83 * Denotes a UI implemented as a Swing dialog. The value of the string is
84 * the fully qualified classname : "javax.swing.JDialog"
85 */
86 public static final String JDIALOG_UI = "javax.swing.JDialog";
87
88 /**
89 * Denotes a UI which performs an informative "About" role.
90 */
91 public static final int ABOUT_UIROLE = 1;
92
93 /**
94 * Denotes a UI which performs an administrative role.
95 */
96 public static final int ADMIN_UIROLE = 2;
97
98 /**
99 * Denotes a UI which performs the normal end user role.
100 */
101 public static final int MAIN_UIROLE = 3;
102
103 /**
104 * Not a valid role but role id's greater than this may be used for private
105 * roles supported by a service. Knowledge of the function performed by this
106 * role is required to make proper use of it.
107 */
108 public static final int RESERVED_UIROLE = 99;
109
110 /**
111 * Get a UI object which may be cast to the requested UI type by the
112 * application and used in its user interface.
113 *
114 * @param role requested. Must be one of the standard roles or a private
115 * role supported by this factory.
116 * @param ui type in which the role is requested
117 * @return the UI role or {@code null} if the requested UI role is not
118 * available from this factory
119 * @throws IllegalArgumentException if the role or ui is neither one of the
120 * standard ones, nor a private one supported by the factory
121 */
122 public abstract Object getUI(int role, String ui) ;
123
124 /**
125 * Given a UI role obtained from this factory obtain the UI types available
126 * from this factory which implement this role. The returned {@code Strings}
127 * should refer to the static variables defined in this class so that
128 * applications can use equality of reference ("==").
129 *
130 * @param role to be looked up
131 * @return the UI types supported by this class for the specified role,
132 * {@code null} if no UIs are available for the role
133 * @throws IllegalArgumentException is the role is a non-standard role not
134 * supported by this factory
135 */
136 public abstract String[] getUIClassNamesForRole(int role) ;
137
138 }