1 /*
   2  * Copyright (c) 2000, 2002, 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 
  27 package javax.print;
  28 
  29 import java.util.ArrayList;
  30 import java.util.Iterator;
  31 import javax.print.attribute.AttributeSet;
  32 
  33 import sun.awt.AppContext;
  34 import java.util.ServiceLoader;
  35 import java.util.ServiceConfigurationError;
  36 
  37 /** Implementations of this class provide lookup services for
  38   * print services (typically equivalent to printers) of a particular type.
  39   * <p>
  40   * Multiple implementations may be installed concurrently.
  41   * All implementations must be able to describe the located printers
  42   * as instances of a PrintService.
  43   * Typically implementations of this service class are located
  44   * automatically in JAR files (see the SPI JAR file specification).
  45   * These classes must be instantiable using a default constructor.
  46   * Alternatively applications may explicitly register instances
  47   * at runtime.
  48   * <p>
  49   * Applications use only the static methods of this abstract class.
  50   * The instance methods are implemented by a service provider in a subclass
  51   * and the unification of the results from all installed lookup classes
  52   * are reported by the static methods of this class when called by
  53   * the application.
  54   * <p>
  55   * A PrintServiceLookup implementor is recommended to check for the
  56   * SecurityManager.checkPrintJobAccess() to deny access to untrusted code.
  57   * Following this recommended policy means that untrusted code may not
  58   * be able to locate any print services. Downloaded applets are the most
  59   * common example of untrusted code.
  60   * <p>
  61   * This check is made on a per lookup service basis to allow flexibility in
  62   * the policy to reflect the needs of different lookup services.
  63   * <p>
  64   * Services which are registered by registerService(PrintService)
  65   * will not be included in lookup results if a security manager is
  66   * installed and its checkPrintJobAccess() method denies access.
  67   */
  68 
  69 public abstract class PrintServiceLookup {
  70 
  71     static class Services {
  72         private ArrayList listOfLookupServices = null;
  73         private ArrayList registeredServices = null;
  74     }
  75 
  76     private static Services getServicesForContext() {
  77         Services services =
  78             (Services)AppContext.getAppContext().get(Services.class);
  79         if (services == null) {
  80             services = new Services();
  81             AppContext.getAppContext().put(Services.class, services);
  82         }
  83         return services;
  84     }
  85 
  86     private static ArrayList getListOfLookupServices() {
  87         return getServicesForContext().listOfLookupServices;
  88     }
  89 
  90     private static ArrayList initListOfLookupServices() {
  91         ArrayList listOfLookupServices = new ArrayList();
  92         getServicesForContext().listOfLookupServices = listOfLookupServices;
  93         return listOfLookupServices;
  94     }
  95 
  96 
  97     private static ArrayList getRegisteredServices() {
  98         return getServicesForContext().registeredServices;
  99     }
 100 
 101     private static ArrayList initRegisteredServices() {
 102         ArrayList registeredServices = new ArrayList();
 103         getServicesForContext().registeredServices = registeredServices;
 104         return registeredServices;
 105     }
 106 
 107     /**
 108      * Locates print services capable of printing the specified
 109      * {@link DocFlavor}.
 110      *
 111      * @param flavor the flavor to print. If null, this constraint is not
 112      *        used.
 113      * @param attributes attributes that the print service must support.
 114      * If null this constraint is not used.
 115      *
 116      * @return array of matching <code>PrintService</code> objects
 117      * representing print services that support the specified flavor
 118      * attributes.  If no services match, the array is zero-length.
 119      */
 120     public static final PrintService[]
 121         lookupPrintServices(DocFlavor flavor,
 122                             AttributeSet attributes) {
 123         ArrayList list = getServices(flavor, attributes);
 124         return (PrintService[])(list.toArray(new PrintService[list.size()]));
 125     }
 126 
 127 
 128     /**
 129      * Locates MultiDoc print Services capable of printing MultiDocs
 130      * containing all the specified doc flavors.
 131      * <P> This method is useful to help locate a service that can print
 132      * a <code>MultiDoc</code> in which the elements may be different
 133      * flavors. An application could perform this itself by multiple lookups
 134      * on each <code>DocFlavor</code> in turn and collating the results,
 135      * but the lookup service may be able to do this more efficiently.
 136      *
 137      * @param flavors the flavors to print. If null or empty this
 138      *        constraint is not used.
 139      * Otherwise return only multidoc print services that can print all
 140      * specified doc flavors.
 141      * @param attributes attributes that the print service must
 142      * support.  If null this constraint is not used.
 143      *
 144      * @return array of matching {@link MultiDocPrintService} objects.
 145      * If no services match, the array is zero-length.
 146      *
 147      */
 148     public static final MultiDocPrintService[]
 149         lookupMultiDocPrintServices(DocFlavor[] flavors,
 150                                     AttributeSet attributes) {
 151         ArrayList list = getMultiDocServices(flavors, attributes);
 152         return (MultiDocPrintService[])
 153             list.toArray(new MultiDocPrintService[list.size()]);
 154     }
 155 
 156 
 157     /**
 158      * Locates the default print service for this environment.
 159      * This may return null.
 160      * If multiple lookup services each specify a default, the
 161      * chosen service is not precisely defined, but a
 162      * platform native service, rather than an installed service,
 163      * is usually returned as the default.  If there is no clearly
 164      * identifiable
 165      * platform native default print service, the default is the first
 166      * to be located in an implementation-dependent manner.
 167      * <p>
 168      * This may include making use of any preferences API that is available
 169      * as part of the Java or native platform.
 170      * This algorithm may be overridden by a user setting the property
 171      * javax.print.defaultPrinter.
 172      * A service specified must be discovered to be valid and currently
 173      * available to be returned as the default.
 174      *
 175      * @return the default PrintService.
 176      */
 177 
 178     public static final PrintService lookupDefaultPrintService() {
 179 
 180         Iterator psIterator = getAllLookupServices().iterator();
 181         while (psIterator.hasNext()) {
 182             try {
 183                 PrintServiceLookup lus = (PrintServiceLookup)psIterator.next();
 184                 PrintService service = lus.getDefaultPrintService();
 185                 if (service != null) {
 186                     return service;
 187                 }
 188             } catch (Exception e) {
 189             }
 190         }
 191         return null;
 192     }
 193 
 194 
 195     /**
 196      * Allows an application to explicitly register a class that
 197      * implements lookup services. The registration will not persist
 198      * across VM invocations.
 199      * This is useful if an application needs to make a new service
 200      * available that is not part of the installation.
 201      * If the lookup service is already registered, or cannot be registered,
 202      * the method returns false.
 203      * <p>
 204      *
 205      * @param sp an implementation of a lookup service.
 206      * @return <code>true</code> if the new lookup service is newly
 207      *         registered; <code>false</code> otherwise.
 208      */
 209     public static boolean registerServiceProvider(PrintServiceLookup sp) {
 210         synchronized (PrintServiceLookup.class) {
 211             Iterator psIterator = getAllLookupServices().iterator();

 212             while (psIterator.hasNext()) {
 213                 try {
 214                     Object lus = psIterator.next();
 215                     if (lus.getClass() == sp.getClass()) {
 216                         return false;
 217                     }
 218                 } catch (Exception e) {
 219                 }
 220             }
 221             getListOfLookupServices().add(sp);
 222             return true;
 223         }
 224 
 225     }
 226 
 227 
 228     /**
 229      * Allows an application to directly register an instance of a
 230      * class which implements a print service.
 231      * The lookup operations for this service will be
 232      * performed by the PrintServiceLookup class using the attribute
 233      * values and classes reported by the service.
 234      * This may be less efficient than a lookup
 235      * service tuned for that service.
 236      * Therefore registering a <code>PrintServiceLookup</code> instance
 237      * instead is recommended.
 238      * The method returns true if this service is not previously
 239      * registered and is now successfully registered.
 240      * This method should not be called with StreamPrintService instances.
 241      * They will always fail to register and the method will return false.
 242      * @param service an implementation of a print service.
 243      * @return <code>true</code> if the service is newly
 244      *         registered; <code>false</code> otherwise.
 245      */
 246 
 247     public static boolean registerService(PrintService service) {
 248         synchronized (PrintServiceLookup.class) {
 249             if (service instanceof StreamPrintService) {
 250                 return false;
 251             }
 252             ArrayList registeredServices = getRegisteredServices();
 253             if (registeredServices == null) {
 254                 registeredServices = initRegisteredServices();
 255             }
 256             else {
 257               if (registeredServices.contains(service)) {
 258                 return false;
 259               }
 260             }
 261             registeredServices.add(service);
 262             return true;
 263         }
 264     }
 265 
 266 
 267    /**
 268     * Locates services that can be positively confirmed to support
 269     * the combination of attributes and DocFlavors specified.
 270     * This method is not called directly by applications.
 271     * <p>
 272     * Implemented by a service provider, used by the static methods
 273     * of this class.
 274     * <p>
 275     * The results should be the same as obtaining all the PrintServices
 276     * and querying each one individually on its support for the
 277     * specified attributes and flavors, but the process can be more
 278     * efficient by taking advantage of the capabilities of lookup services
 279     * for the print services.
 280     *
 281     * @param flavor of document required.  If null it is ignored.
 282     * @param attributes required to be supported. If null this
 283     * constraint is not used.
 284     * @return array of matching PrintServices. If no services match, the
 285     * array is zero-length.
 286     */
 287     public abstract PrintService[] getPrintServices(DocFlavor flavor,
 288                                                     AttributeSet attributes);
 289 
 290     /**
 291      * Not called directly by applications.
 292      * Implemented by a service provider, used by the static methods
 293      * of this class.
 294      * @return array of all PrintServices known to this lookup service
 295      * class. If none are found, the array is zero-length.
 296      */
 297     public abstract PrintService[] getPrintServices() ;
 298 
 299 
 300    /**
 301     * Not called directly by applications.
 302     * <p>
 303     * Implemented by a service provider, used by the static methods
 304     * of this class.
 305     * <p>
 306     * Locates MultiDoc print services which can be positively confirmed
 307     * to support the combination of attributes and DocFlavors specified.
 308     * <p>
 309     *
 310     * @param flavors of documents required. If null or empty it is ignored.
 311     * @param attributes required to be supported. If null this
 312      * constraint is not used.
 313     * @return array of matching PrintServices. If no services match, the
 314     * array is zero-length.
 315     */
 316     public abstract MultiDocPrintService[]
 317         getMultiDocPrintServices(DocFlavor[] flavors,
 318                                  AttributeSet attributes);
 319 
 320     /**
 321      * Not called directly by applications.
 322      * Implemented by a service provider, and called by the print lookup
 323      * service
 324      * @return the default PrintService for this lookup service.
 325      * If there is no default, returns null.
 326      */
 327     public abstract PrintService getDefaultPrintService();
 328 
 329     private static ArrayList getAllLookupServices() {
 330         synchronized (PrintServiceLookup.class) {
 331             ArrayList listOfLookupServices = getListOfLookupServices();
 332             if (listOfLookupServices != null) {
 333                 return listOfLookupServices;
 334             } else {
 335                 listOfLookupServices = initListOfLookupServices();
 336             }
 337             try {
 338                 java.security.AccessController.doPrivileged(
 339                      new java.security.PrivilegedExceptionAction() {
 340                         public Object run() {
 341                             Iterator<PrintServiceLookup> iterator =
 342                                 ServiceLoader.load(PrintServiceLookup.class).
 343                                 iterator();
 344                             ArrayList los = getListOfLookupServices();
 345                             while (iterator.hasNext()) {
 346                                 try {
 347                                     los.add(iterator.next());
 348                                 }  catch (ServiceConfigurationError err) {
 349                                     /* In the applet case, we continue */
 350                                     if (System.getSecurityManager() != null) {
 351                                         err.printStackTrace();
 352                                     } else {
 353                                         throw err;
 354                                     }
 355                                 }
 356                             }
 357                             return null;
 358                         }
 359                 });
 360             } catch (java.security.PrivilegedActionException e) {
 361             }
 362 
 363             return listOfLookupServices;
 364         }
 365     }
 366 
 367     private static ArrayList getServices(DocFlavor flavor,
 368                                          AttributeSet attributes) {
 369 
 370         ArrayList listOfServices = new ArrayList();
 371         Iterator psIterator = getAllLookupServices().iterator();
 372         while (psIterator.hasNext()) {
 373             try {
 374                 PrintServiceLookup lus = (PrintServiceLookup)psIterator.next();
 375                 PrintService[] services=null;
 376                 if (flavor == null && attributes == null) {
 377                     try {
 378                     services = lus.getPrintServices();
 379                     } catch (Throwable tr) {
 380                     }
 381                 } else {
 382                     services = lus.getPrintServices(flavor, attributes);
 383                 }
 384                 if (services == null) {
 385                     continue;
 386                 }
 387                 for (int i=0; i<services.length; i++) {
 388                     listOfServices.add(services[i]);
 389                 }
 390             } catch (Exception e) {
 391             }
 392         }
 393         /* add any directly registered services */
 394         ArrayList registeredServices = null;
 395         try {
 396           SecurityManager security = System.getSecurityManager();
 397           if (security != null) {
 398             security.checkPrintJobAccess();
 399           }
 400           registeredServices = getRegisteredServices();
 401         } catch (SecurityException se) {
 402         }
 403         if (registeredServices != null) {
 404             PrintService[] services = (PrintService[])
 405                 registeredServices.toArray(
 406                            new PrintService[registeredServices.size()]);
 407             for (int i=0; i<services.length; i++) {
 408                 if (!listOfServices.contains(services[i])) {
 409                     if (flavor == null && attributes == null) {
 410                         listOfServices.add(services[i]);
 411                     } else if (((flavor != null &&
 412                                  services[i].isDocFlavorSupported(flavor)) ||
 413                                 flavor == null) &&
 414                                null == services[i].getUnsupportedAttributes(
 415                                                       flavor, attributes)) {
 416                         listOfServices.add(services[i]);
 417                     }
 418                 }
 419             }
 420         }
 421         return listOfServices;
 422     }
 423 
 424     private static ArrayList getMultiDocServices(DocFlavor[] flavors,
 425                                                  AttributeSet attributes) {
 426 
 427 
 428         ArrayList listOfServices = new ArrayList();
 429         Iterator psIterator = getAllLookupServices().iterator();
 430         while (psIterator.hasNext()) {
 431             try {
 432                 PrintServiceLookup lus = (PrintServiceLookup)psIterator.next();
 433                 MultiDocPrintService[] services  =
 434                     lus.getMultiDocPrintServices(flavors, attributes);
 435                 if (services == null) {
 436                     continue;
 437                 }
 438                 for (int i=0; i<services.length; i++) {
 439                     listOfServices.add(services[i]);
 440                 }
 441             } catch (Exception e) {
 442             }
 443         }
 444         /* add any directly registered services */
 445         ArrayList registeredServices = null;
 446         try {
 447           SecurityManager security = System.getSecurityManager();
 448           if (security != null) {
 449             security.checkPrintJobAccess();
 450           }
 451           registeredServices = getRegisteredServices();
 452         } catch (Exception e) {
 453         }
 454         if (registeredServices != null) {
 455             PrintService[] services = (PrintService[])
 456                 registeredServices.toArray(
 457                            new PrintService[registeredServices.size()]);
 458             for (int i=0; i<services.length; i++) {
 459                 if (services[i] instanceof MultiDocPrintService &&
 460                     !listOfServices.contains(services[i])) {
 461                     if (flavors == null || flavors.length == 0) {
 462                         listOfServices.add(services[i]);
 463                     } else {
 464                         boolean supported = true;
 465                         for (int f=0; f<flavors.length; f++) {
 466                             if (services[i].isDocFlavorSupported(flavors[f])) {
 467 
 468                                 if (services[i].getUnsupportedAttributes(
 469                                      flavors[f], attributes) != null) {
 470                                         supported = false;
 471                                         break;
 472                                 }
 473                             } else {
 474                                 supported = false;
 475                                 break;
 476                             }
 477                         }
 478                         if (supported) {
 479                             listOfServices.add(services[i]);
 480                         }
 481                     }
 482                 }
 483             }
 484         }
 485         return listOfServices;
 486     }
 487 
 488 }
--- EOF ---