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