--- old/src/java.desktop/share/classes/javax/print/PrintServiceLookup.java 2017-07-16 16:17:21.000000000 -0700 +++ new/src/java.desktop/share/classes/javax/print/PrintServiceLookup.java 2017-07-16 16:17:21.000000000 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -23,56 +23,69 @@ * questions. */ - package javax.print; import java.util.ArrayList; import java.util.Iterator; +import java.util.ServiceConfigurationError; +import java.util.ServiceLoader; + import javax.print.attribute.AttributeSet; import sun.awt.AppContext; -import java.util.ServiceLoader; -import java.util.ServiceConfigurationError; - -/** Implementations of this class provide lookup services for - * print services (typically equivalent to printers) of a particular type. - *
- * Multiple implementations may be installed concurrently. - * All implementations must be able to describe the located printers - * as instances of a PrintService. - * Typically implementations of this service class are located - * automatically in JAR files (see the SPI JAR file specification). - * These classes must be instantiable using a default constructor. - * Alternatively applications may explicitly register instances - * at runtime. - *
- * Applications use only the static methods of this abstract class. - * The instance methods are implemented by a service provider in a subclass - * and the unification of the results from all installed lookup classes - * are reported by the static methods of this class when called by - * the application. - *
- * A PrintServiceLookup implementor is recommended to check for the - * SecurityManager.checkPrintJobAccess() to deny access to untrusted code. - * Following this recommended policy means that untrusted code may not - * be able to locate any print services. Downloaded applets are the most - * common example of untrusted code. - *
- * This check is made on a per lookup service basis to allow flexibility in - * the policy to reflect the needs of different lookup services. - *
- * Services which are registered by registerService(PrintService) - * will not be included in lookup results if a security manager is - * installed and its checkPrintJobAccess() method denies access. - */ +/** + * Implementations of this class provide lookup services for print services + * (typically equivalent to printers) of a particular type. + *
+ * Multiple implementations may be installed concurrently. All implementations + * must be able to describe the located printers as instances of a + * {@code PrintService}. Typically implementations of this service class are + * located automatically in JAR files (see the SPI JAR file specification). + * These classes must be instantiable using a default constructor. Alternatively + * applications may explicitly register instances at runtime. + *
+ * Applications use only the static methods of this abstract class. The instance + * methods are implemented by a service provider in a subclass and the + * unification of the results from all installed lookup classes are reported by + * the static methods of this class when called by the application. + *
+ * A {@code PrintServiceLookup} implementor is recommended to check for the + * {@code SecurityManager.checkPrintJobAccess()} to deny access to untrusted + * code. Following this recommended policy means that untrusted code may not be + * able to locate any print services. Downloaded applets are the most common + * example of untrusted code. + *
+ * This check is made on a per lookup service basis to allow flexibility in the + * policy to reflect the needs of different lookup services. + *
+ * Services which are registered by {@link #registerService(PrintService)} will
+ * not be included in lookup results if a security manager is installed and its
+ * {@code checkPrintJobAccess()} method denies access.
+ */
public abstract class PrintServiceLookup {
+ /**
+ * Contains a lists of services.
+ */
static class Services {
+
+ /**
+ * The list of lookup services.
+ */
private ArrayList This method is useful to help locate a service that can print
- * a {@code MultiDoc} in which the elements may be different
- * flavors. An application could perform this itself by multiple lookups
- * on each {@code DocFlavor} in turn and collating the results,
- * but the lookup service may be able to do this more efficiently.
- *
- * @param flavors the flavors to print. If null or empty this
- * constraint is not used.
- * Otherwise return only multidoc print services that can print all
- * specified doc flavors.
- * @param attributes attributes that the print service must
- * support. If null this constraint is not used.
- *
- * @return array of matching {@link MultiDocPrintService} objects.
- * If no services match, the array is zero-length.
+ * Locates {@code MultiDoc} print {@code Services} capable of printing
+ * {@code MultiDocs} containing all the specified doc flavors.
+ *
+ * This method is useful to help locate a service that can print a
+ * {@code MultiDoc} in which the elements may be different flavors. An
+ * application could perform this itself by multiple lookups on each
+ * {@code DocFlavor} in turn and collating the results, but the lookup
+ * service may be able to do this more efficiently.
*
+ * @param flavors the flavors to print. If {@code null} or empty this
+ * constraint is not used. Otherwise return only multidoc print
+ * services that can print all specified doc flavors.
+ * @param attributes attributes that the print service must support. If
+ * {@code null} this constraint is not used.
+ * @return array of matching {@link MultiDocPrintService} objects. If no
+ * services match, the array is zero-length.
*/
public static final MultiDocPrintService[]
lookupMultiDocPrintServices(DocFlavor[] flavors,
@@ -152,28 +180,23 @@
return list.toArray(new MultiDocPrintService[list.size()]);
}
-
/**
- * Locates the default print service for this environment.
- * This may return null.
- * If multiple lookup services each specify a default, the
- * chosen service is not precisely defined, but a
- * platform native service, rather than an installed service,
- * is usually returned as the default. If there is no clearly
- * identifiable
- * platform native default print service, the default is the first
- * to be located in an implementation-dependent manner.
+ * Locates the default print service for this environment. This may return
+ * {@code null}. If multiple lookup services each specify a default, the
+ * chosen service is not precisely defined, but a platform native service,
+ * rather than an installed service, is usually returned as the default. If
+ * there is no clearly identifiable platform native default print service,
+ * the default is the first to be located in an implementation-dependent
+ * manner.
*
- * This may include making use of any preferences API that is available
- * as part of the Java or native platform.
- * This algorithm may be overridden by a user setting the property
- * javax.print.defaultPrinter.
- * A service specified must be discovered to be valid and currently
- * available to be returned as the default.
+ * This may include making use of any preferences API that is available as
+ * part of the Java or native platform. This algorithm may be overridden by
+ * a user setting the property {@code javax.print.defaultPrinter}. A service
+ * specified must be discovered to be valid and currently available to be
+ * returned as the default.
*
- * @return the default PrintService.
+ * @return the default {@code PrintService}
*/
-
public static final PrintService lookupDefaultPrintService() {
Iterator
- * Implemented by a service provider, used by the static methods
- * of this class.
- *
- * The results should be the same as obtaining all the PrintServices
- * and querying each one individually on its support for the
- * specified attributes and flavors, but the process can be more
- * efficient by taking advantage of the capabilities of lookup services
- * for the print services.
- *
- * @param flavor of document required. If null it is ignored.
- * @param attributes required to be supported. If null this
- * constraint is not used.
- * @return array of matching PrintServices. If no services match, the
- * array is zero-length.
- */
+ /**
+ * Locates services that can be positively confirmed to support the
+ * combination of attributes and {@code DocFlavors} specified. This method
+ * is not called directly by applications.
+ *
+ * Implemented by a service provider, used by the static methods of this
+ * class.
+ *
+ * The results should be the same as obtaining all the {@code PrintServices}
+ * and querying each one individually on its support for the specified
+ * attributes and flavors, but the process can be more efficient by taking
+ * advantage of the capabilities of lookup services for the print services.
+ *
+ * @param flavor of document required. If {@code null} it is ignored.
+ * @param attributes required to be supported. If {@code null} this
+ * constraint is not used.
+ * @return array of matching {@code PrintServices}. If no services match,
+ * the array is zero-length.
+ */
public abstract PrintService[] getPrintServices(DocFlavor flavor,
AttributeSet attributes);
/**
- * Not called directly by applications.
- * Implemented by a service provider, used by the static methods
- * of this class.
- * @return array of all PrintServices known to this lookup service
- * class. If none are found, the array is zero-length.
+ * Not called directly by applications. Implemented by a service provider,
+ * used by the static methods of this class.
+ *
+ * @return array of all {@code PrintServices} known to this lookup service
+ * class. If none are found, the array is zero-length.
*/
public abstract PrintService[] getPrintServices() ;
-
- /**
- * Not called directly by applications.
- *
- * Implemented by a service provider, used by the static methods
- * of this class.
- *
- * Locates MultiDoc print services which can be positively confirmed
- * to support the combination of attributes and DocFlavors specified.
- *
- * @param flavors of documents required. If null or empty it is ignored.
- * @param attributes required to be supported. If null this
- * constraint is not used.
- * @return array of matching PrintServices. If no services match, the
- * array is zero-length.
- */
+ /**
+ * Not called directly by applications.
+ *
+ * Implemented by a service provider, used by the static methods of this
+ * class.
+ *
+ * Locates {@code MultiDoc} print services which can be positively confirmed
+ * to support the combination of attributes and {@code DocFlavors}
+ * specified.
+ *
+ * @param flavors of documents required. If {@code null} or empty it is
+ * ignored.
+ * @param attributes required to be supported. If {@code null} this
+ * constraint is not used.
+ * @return array of matching {@code PrintServices}. If no services match,
+ * the array is zero-length.
+ */
public abstract MultiDocPrintService[]
getMultiDocPrintServices(DocFlavor[] flavors,
AttributeSet attributes);
/**
- * Not called directly by applications.
- * Implemented by a service provider, and called by the print lookup
- * service
- * @return the default PrintService for this lookup service.
- * If there is no default, returns null.
+ * Not called directly by applications. Implemented by a service provider,
+ * and called by the print lookup service.
+ *
+ * @return the default {@code PrintService} for this lookup service. If
+ * there is no default, returns {@code null}.
*/
public abstract PrintService getDefaultPrintService();
+ /**
+ * Returns all lookup services for this environment.
+ *
+ * @return all lookup services for this environment
+ */
private static ArrayList