+ * The applet framework involves two entities: the applet and the + * applet context. An applet is an embeddable window (see the Panel + * class) with a few extra methods that the applet context can use to + * initialize, start, and stop the applet. + *
+ * The applet context is an application that is responsible for loading and + * running applets. For example, the applet context could be a Web browser or an + * applet development environment. + *
+ * The APIs in this package are all deprecated. Alternative technologies such as + * Java Web Start or installable applications should be used instead. + * See JEP 289 and + * the Oracle White Paper + * + * "Migrating from Java Applets to plugin-free Java technologies" for more + * information. + * + * @since 1.0 + */ +package java.applet; diff --git a/jdk/src/java.desktop/share/classes/java/applet/package.html b/jdk/src/java.desktop/share/classes/java/applet/package.html deleted file mode 100644 index a95395b900e..00000000000 --- a/jdk/src/java.desktop/share/classes/java/applet/package.html +++ /dev/null @@ -1,65 +0,0 @@ - - - - -
- -Provides the classes necessary to create an applet and the classes an applet -uses to communicate with its applet context. --The applet framework involves two -entities: the applet and the applet context. An applet is an -embeddable window (see the Panel class) with a few extra methods that the applet -context can use to initialize, start, and stop the applet. -
-The applet context is an application that is responsible for loading and running -applets. For example, the applet context could be a Web browser or an applet -development environment. -
-The APIs in this package are all deprecated. Alternative technologies such as Java Web Start -or installable applications should be used instead. See JEP 289 -and the Oracle White Paper -"Migrating from Java Applets to plugin-free Java technologies" for more information. -
- - -@since 1.0 - - diff --git a/jdk/src/java.desktop/share/classes/java/beans/beancontext/package-info.java b/jdk/src/java.desktop/share/classes/java/beans/beancontext/package-info.java new file mode 100644 index 00000000000..f1b22cf7da0 --- /dev/null +++ b/jdk/src/java.desktop/share/classes/java/beans/beancontext/package-info.java @@ -0,0 +1,36 @@ +/* + * Copyright (c) 1998, 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Provides classes and interfaces relating to bean context. A bean context is a + * container for beans and defines the execution environment for the beans it + * contains. There can be several beans in a single bean context, and a bean + * context can be nested within another bean context. This package also + * contains events and listener interface for beans being added and removed from + * a bean context. + * + * @since 1.2 + */ +package java.beans.beancontext; diff --git a/jdk/src/java.desktop/share/classes/java/beans/beancontext/package.html b/jdk/src/java.desktop/share/classes/java/beans/beancontext/package.html deleted file mode 100644 index 739356e24fa..00000000000 --- a/jdk/src/java.desktop/share/classes/java/beans/beancontext/package.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - -
- -Provides classes and interfaces relating to bean context. -A bean context is a container for beans and defines the execution -environment for the beans it contains. There can be several beans in -a single bean context, and a bean context can be nested within another -bean context. This package also contains events and listener -interface for beans being added and removed from a bean context. - - - -@since 1.2 - - diff --git a/jdk/src/java.desktop/share/classes/java/beans/package-info.java b/jdk/src/java.desktop/share/classes/java/beans/package-info.java new file mode 100644 index 00000000000..c841669ac0e --- /dev/null +++ b/jdk/src/java.desktop/share/classes/java/beans/package-info.java @@ -0,0 +1,112 @@ +/* + * Copyright (c) 1998, 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Contains classes related to developing beans -- components based on + * the JavaBeans™ architecture. A few of the classes are used by beans + * while they run in an application. For example, the event classes are used by + * beans that fire property and vetoable change events (see + * {@link java.beans.PropertyChangeEvent}). However, most of the classes in this + * package are meant to be used by a bean editor (that is, a development + * environment for customizing and putting together beans to create an + * application). In particular, these classes help the bean editor create a user + * interface that the user can use to customize the bean. For example, a bean + * may contain a property of a special type that a bean editor may not know how + * to handle. By using the {@code PropertyEditor} interface, a bean developer + * can provide an editor for this special type. + *+ * To minimize the resources used by a bean, the classes used by bean editors + * are loaded only when the bean is being edited. They are not needed while the + * bean is running in an application and therefore not loaded. This information + * is kept in what's called a bean-info (see {@link java.beans.BeanInfo}). + *
+ * Unless explicitly stated, null values or empty Strings are not valid + * parameters for the methods in this package. You may expect to see exceptions + * if these parameters are used. + * + *
+ *
Note: The persistence scheme cannot automatically + * instantiate custom inner classes, such as you might use for event handlers. + * By using the {@link java.beans.EventHandler} class instead of inner classes + * for custom event handlers, you can avoid this problem.
+ * You read and write beans in XML format using the + * {@link java.beans.XMLDecoder} and {@link java.beans.XMLEncoder} classes, + * respectively. One notable feature of the persistence scheme is that reading + * in a bean requires no special knowledge of the bean. + *
+ * Writing out a bean, on the other hand, sometimes requires special knowledge + * of the bean's type. If the bean's state can be expressed using only the + * no-argument constructor and public getter and setter methods for properties, + * no special knowledge is required. Otherwise, the bean requires a custom + * persistence delegate -- an object that is in charge of writing out + * beans of a particular type. All classes provided in the JDK that descend from + * {@code java.awt.Component}, as well as all their properties, automatically + * have persistence delegates. + *
+ * If you need (or choose) to provide a persistence delegate for a bean, you can + * do so either by using a {@link java.beans.DefaultPersistenceDelegate} + * instance or by creating your own subclass of {@code PersistenceDelegate}. If + * the only reason a bean needs a persistence delegate is because you want to + * invoke the bean's constructor with property values as arguments, you can + * create the bean's persistence delegate with the one-argument + * {@code DefaultPersistenceDelegate} constructor. Otherwise, you need to + * implement your own persistence delegate, for which you're likely to need the + * following classes: + *
+ * Once you create a persistence delegate, you register it using the + * {@code setPersistenceDelegate} method of {@code XMLEncoder}. + * + *
PropertyEditor interface, a bean developer can
-provide an editor for this special type.
-
--To minimize the resources used by a bean, the classes used by bean editors are loaded only -when the bean is being edited. They are not needed while the bean is running in an application -and therefore not loaded. This information is kept in what's called a bean-info (see {@link java.beans.BeanInfo}). - -
-Unless explicitly stated, null values or empty Strings are not valid -parameters for the methods in this package. You may expect to see -exceptions if these parameters are used. - - -
java.beans package provides support for
-long-term persistence -- reading and
-writing a bean as a textual representation of its property values.
-The property values are treated as beans,
-and are recursively read or written to capture
-their publicly available state.
-This approach is suitable for long-term storage
-because it relies only on public API,
-rather than the likely-to-change private implementation.
-
--- -
-Note: -The persistence scheme cannot automatically instantiate -custom inner classes, such as you might use for event handlers. -By using the {@link java.beans.EventHandler} class -instead of inner classes for custom event handlers, -you can avoid this problem. -
-
- -You read and write beans in XML format using the -{@link java.beans.XMLDecoder} -and -{@link java.beans.XMLEncoder} -classes, respectively. -One notable feature of the persistence scheme is that -reading in a bean requires no special knowledge of the bean. - -
-Writing out a bean, on the other hand,
-sometimes requires special knowledge of the bean's type.
-If the bean's state can be
-expressed using only the no-argument constructor and
-public getter and setter methods for properties,
-no special knowledge is required.
-Otherwise, the bean requires a custom persistence delegate --
-an object that is in charge of writing out beans of a particular type.
-All classes provided in the JDK that descend
-from java.awt.Component,
-as well as all their properties,
-automatically have persistence delegates.
-
-
-
-If you need (or choose) to provide a persistence delegate for a bean,
-you can do so either by using a
-{@link java.beans.DefaultPersistenceDelegate}
-instance
-or by creating your own subclass of PersistenceDelegate.
-If the only reason a bean needs a persistence delegate
-is because you want to invoke the bean's constructor with
-property values as arguments,
-you can create the bean's persistence delegate
-with the one-argument
-DefaultPersistenceDelegate
-constructor.
-Otherwise,
-you need to implement your own persistence delegate,
-for which you're likely to need the following classes:
-
-
Statements and Expressions
- are necessary to create the bean
- and restore its state.
-Statement
- used for methods that return a value.
-
-Once you create a persistence delegate,
-you register it using the
-setPersistenceDelegate method of
-XMLEncoder.
-
-
-
+ * The Java Accessibility API package consists of 8 Java programming language + * interfaces, and 6 Java programming language classes. These are described + * below. + * + *
+ * The constants in this class present a strongly typed enumeration of common + * object roles. A public constructor for this class has been purposely omitted + * and applications should use one of the constants from this class. Although + * this class pre-defines a large list of standard roles, it is extensible so + * additional, programmer-defined roles can be added in the future without + * needing to modify the base class. + * + *
+ * Applications can determine if an object supports the AccessibleAction + * interface by first obtaining its + * AccessibleContext (see + * Accessible) and then calling the + * {@code getAccessibleAction} method of + * AccessibleContext. If the return value is + * not null, the object supports this interface. + * + *
Applications + * can determine if an object supports the AccessibleComponent interface by + * first obtaining its AccessibleContext (see + * Accessible) and then calling the + * {@code getAccessibleComponent} method of + * AccessibleContext. If the return value is + * not null, the object supports this interface. + * + *
+ * Applications can determine if an object supports the AccessibleSelection + * interface by first obtaining its + * AccessibleContext (see + * Accessible) and then calling the + * {@code getAccessibleSelection} method of + * AccessibleContext. If the return value is + * not null, the object supports this interface. + * + *
+ * This interface provides support for going between pixel coordinates and the + * text at a given pixel coordinate, for retrieving the letter, word, and + * sentence at, before, or after a given position in the text. This interface + * provides support for retrieving the attributes of the character at a given + * position in the text (font, font size, style, etc.), as well as getting the + * selected text (if any), the length of the text, and the location of the text + * caret. + *
+ * Applications can determine if an object supports the AccessibleText interface + * by first obtaining its AccessibleContext + * (see Accessible) and then calling the + * {@code getAccessibleText} method of + * AccessibleContext. If the return value is + * not null, the object supports this interface. + * + *
+ * Applications can determine if an object supports the AccessibleValue + * interface by first obtaining its + * AccessibleContext (see + * Accessible) and then calling the + * {@code getAccessibleValue} method of + * AccessibleContext. If the return value is + * not null, the object supports this interface. + * + * @since 1.2 + */ +package javax.accessibility; diff --git a/jdk/src/java.desktop/share/classes/javax/accessibility/package.html b/jdk/src/java.desktop/share/classes/javax/accessibility/package.html deleted file mode 100644 index 4d1037aeb8b..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/accessibility/package.html +++ /dev/null @@ -1,266 +0,0 @@ - -
- - - - - -Defines a contract between user-interface components and an assistive technology -that provides access to those components. If a Java application fully supports -the Java Accessibility API, then it should be compatible with, and friendly -toward, assistive technologies such as screen readers, screen magnifiers, -etc. With a Java application that fully supports the Java Accessibility -API, no screen reader off screen model would be necessary because the API -provides all of the information normally contained in an off screen model. - -The Java Accessibility API package consists of 8 Java programming language -interfaces, and 6 Java programming language classes. These are described -below. -
getAccessibleContext,
-that returns an instance of the class AccessibleContext.
-Sun thinks that implementing this interface is the absolute minimum requirement
-of every object that is part of the user interface of a Java application,
-if that program is to be compatible with assistive technologies.
-getAccessibleContext method on an object that implements the Accessible
-interface. This information includes the accessible name, description,
-role, and state
-of the object, as well as information about the parent and children of
-the object. In addition, JavaBeans TM
-property change support is also included to allow assisitive technologies
-learn when the values of the accessible properties change. AccessibleContext
-also contains methods for obtaining more specific accessibility information
-about a component. If the component supports it, these methods will return
-an object that implements one or more of the following interfaces:
-getAccessibleAction
-method is called on an AccessibleContext.getAccessibleComponent
-method is called on an AccessibleContext.getAccessibleSelection method is called on an AccessibleContext.getAccessibleText method is called on an AccessibleContext.getAccessibleText method is called on an AccessibleContext.getAccessibleValue
-method is called on an AccessibleContext.getAccessibleRole method on an
-AccessibleContext. Accessible roles include
-"Check box", "Menu Item", "Panel", etc. These roles are identified by the
-constants in this class such as AccessibleRole.CHECK_BOX, AccessibleRole.MENU_ITEM,
-and AccessibleRole.PANEL. The constants in this class present
-a strongly typed enumeration of common object roles. A public constructor
-for this class has been purposely omitted and applications should use one
-of the constants from this class. Although this class pre-defines a large
-list of standard roles, it is extensible so additional programmer-defined
-roles can be added in the future without needing to modify the base class.
-
-AccessibleState.ARMED,
-AccessibleState.BUSY, AccessibleState.CHECKED, and AccessibleState.FOCUSED.
-The sum of all the states of an Accessible object is called the AccessibleStateSet,
-and can be obtained by calling the getAccessibleStateSet method
-on an AccessibleContext.
-
-The constants in this class present a strongly typed enumeration of -common object roles. A public constructor for this class has been purposely -omitted and applications should use one of the constants from this class. -Although this class pre-defines a large list of standard roles, it is extensible -so additional, programmer-defined roles can be added in the future without -needing to modify the base class. - -
getAccessibleStateSet method on
-an AccessibleContext. Since an object
-might have multiple states (e.g. it might be both "Checked" and "Focused"),
-this class is needed to encapsulate a collection of these states. Methods
-in the class provide for retrieving the individual AccessibleStates
-on the state set.
-Applications can determine if an object supports the AccessibleAction
-interface by first obtaining its AccessibleContext
-(see Accessible) and then calling the getAccessibleAction
-method of AccessibleContext. If the return
-value is not null, the object supports this interface.
-
Applications can determine if an object supports the AccessibleComponent
-interface by first obtaining its AccessibleContext
-(see Accessible) and then calling the getAccessibleComponent
-method of AccessibleContext. If the return
-value is not null, the object supports this interface.
-
Applications can determine if an object supports the AccessibleSelection
-interface by first obtaining its AccessibleContext
-(see Accessible) and then calling the getAccessibleSelection
-method of AccessibleContext. If the return
-value is not null, the object supports this interface.
-
This interface provides support for going between pixel coordinates -and the text at a given pixel coordinate, for retrieving the letter, word, -and sentence at, before, or after a given position in the text. This interface -provides support for retrieving the attributes of the character at a given -position in the text (font, font size, style, etc.), as well as getting -the selected text (if any), the length of the text, and the location of -the text caret. - -
Applications can determine if an object supports the AccessibleText
-interface by first obtaining its AccessibleContext
-(see Accessible) and then calling the getAccessibleText
-method of AccessibleContext. If the return
-value is not null, the object supports this interface.
-
Applications can determine if an object supports the AccessibleValue
-interface by first obtaining its AccessibleContext
-(see Accessible) and then calling the getAccessibleValue
-method of AccessibleContext. If the return
-value is not null, the object supports this interface.
-
-@since 1.2
-
-
-
diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/event/package-info.java b/jdk/src/java.desktop/share/classes/javax/imageio/event/package-info.java
new file mode 100644
index 00000000000..2c2ebcf7f95
--- /dev/null
+++ b/jdk/src/java.desktop/share/classes/javax/imageio/event/package-info.java
@@ -0,0 +1,45 @@
+/*
+ * 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * A package of the Java Image I/O API dealing with synchronous notification of
+ * events during the reading and writing of images.
+ *
+ * The {@code IIOReadProgressListener} interface allows for notification of the + * percentage of an image that has been read successfully. + *
+ * The {@code IIOReadUpdateListener} interface allows for notification of the + * portions of an image that have been read. This is useful, for example, for + * implementing dynamic display of an image as it is loaded. + *
+ * The {@code IIOReadWarningListener} interface allows for notification of + * non-fatal errors during reading. + *
+ * The {@code IIOWriteWarningListener} and {@code IIOWriteProgressListener} + * interfaces perform analogous functions for writers. + * + * @since 1.4 + */ +package javax.imageio.event; diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/event/package.html b/jdk/src/java.desktop/share/classes/javax/imageio/event/package.html deleted file mode 100644 index 000ab8bde0a..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/imageio/event/package.html +++ /dev/null @@ -1,62 +0,0 @@ - - -
- - - - - - -A package of the Java Image I/O API dealing with synchronous -notification of events during the reading and writing of images. - -
-
-The IIOReadProgressListener interface allows for
-notification of the percentage of an image that has been read
-successfully.
-
-
-
-The IIOReadUpdateListener interface allows for
-notification of the portions of an image that have been read. This is
-useful, for example, for implementing dynamic display of an image as
-it is loaded.
-
-
-
-The IIOReadWarningListener interface allows for
-notification of non-fatal errors during reading.
-
-
-
-The IIOWriteWarningListener and
-IIOWriteProgressListener interfaces perform analogous
-functions for writers.
-
-@since 1.4
-
-
diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/metadata/package-info.java b/jdk/src/java.desktop/share/classes/javax/imageio/metadata/package-info.java
new file mode 100644
index 00000000000..e9d75bcf1a5
--- /dev/null
+++ b/jdk/src/java.desktop/share/classes/javax/imageio/metadata/package-info.java
@@ -0,0 +1,73 @@
+/*
+ * 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * A package of the Java Image I/O API dealing with reading and writing
+ * metadata.
+ *
+ * When reading an image, its per-stream and per-image metadata is made + * available as an {@code IIOMetadata} object. The internals of this object are + * specific to the plug-in that created it. Its contents may be accessed in the + * form of an XML {@code Document}, which is implemented as a tree of + * {@code IIOMetadataNode} objects. + *
+ * When writing an image, its metadata may be set by defining or modifying an + * {@code IIOMetadata} object. Such an object may be obtained from an + * {@code ImageWriter} or {@code ImageTranscoder} (from the + * {@code javax.imageio} package). Once such an object has been obtained, its + * contents may be set of modified via a {@code Document} consisting of + * {@code IIOMetadataNode}s. The document format may optionally be described + * using an {@code IIOMetadataFormat} object. + *
+ * The format of the metadata contained in the XML {@code Document} is + * identified by a string which appears as the root node of the tree of + * {@code IIOMetadataNode} objects. This string contains a version number, e.g. + * "javax_imageio_jpeg_image_1.0". Readers and writers may support multiple + * versions of the same basic format and the Image I/O API has methods that + * allow specifying which version to use by passing the string to the + * method/constructor used to obtain an {@code IIOMetadata} object. In some + * cases, a more recent version may not be strictly compatible with a program + * written expecting an older version (for an example, see the Native Metadata + * Format section of the JPEG Metadata Usage Notes below). + *
+ * Plug-ins may choose to support a + * standard (plug-in neutral) format + * . This format does not provide lossless encoding of metadata, but allows + * a portion of the metadata to be accessed in a generic manner. + *
+ * Each of the standard plug-ins supports a so-called "native" metadata format, + * which encodes its metadata losslessly: + *
-
-When reading an image, its per-stream and per-image metadata is made
-available as an IIOMetadata object. The internals of
-this object are specific to the plug-in that created it. Its contents
-may be accessed in the form of an XML Document, which is
-implemented as a tree of IIOMetadataNode objects.
-
-
-
-When writing an image, its metadata may be set by defining or
-modifying an IIOMetadata object. Such an object may be
-obtained from an ImageWriter or
-ImageTranscoder (from the
-javax.imageio package). Once such an object has
-been obtained, its contents may be set of modified via a
-Document consisting of IIOMetadataNodes.
-The document format may optionally be described using an
-IIOMetadataFormat object.
-
-
-
-The format of the metadata contained in the XML Document
-is identified by a string which appears as the root node of the tree
-of IIOMetadataNode objects. This string contains a version
-number, e.g. "javax_imageio_jpeg_image_1.0". Readers and writers may
-support multiple versions of the same basic format and the Image I/O
-API has methods that allow specifying which version to use by passing
-the string to the method/constructor used to obtain an IIOMetadata
-object. In some cases, a more recent version may not be strictly
-compatible with a program written expecting an older version (for
-an example, see the Native Metadata Format section of the JPEG Metadata
-Usage Notes below).
-
-
- -Plug-ins may choose to support a standard (plug-in neutral) -format. This format does not provide lossless encoding of -metadata, but allows a portion of the metadata to be accessed in a -generic manner. - -
- -Each of the standard plug-ins supports a so-called "native" metadata -format, which encodes its metadata losslessly: - -
+ * Many common image I/O operations may be performed using the static methods of + * the {@code ImageIO} class. + *
+ * This package contains the basic classes and interfaces for describing the + * contents of image files, including metadata and thumbnails + * ({@code IIOImage}); for controlling the image reading process + * ({@code ImageReader}, {@code ImageReadParam}, and {@code ImageTypeSpecifier}) + * and image writing process ({@code ImageWriter} and {@code ImageWriteParam}); + * for performing transcoding between formats ({@code ImageTranscoder}), and for + * reporting errors ({@code IIOException}). + *
+ * All implementations of javax.imageio provide the following standard image + * format plug-ins: + *
| Reading | Writing | Notes | + *Metadata | + *|
|---|---|---|---|---|
| + * BMP | + *yes | + *yes | + *none | + *BMP + * metadata format | + *
| GIF + * | + *yes | + *yes | + *GIF plug-in notes + * | + *GIF + * metadata format | + *
| JPEG | + *yes | + *yes | + *none | + *+ * JPEG metadata format | + *
| PNG | + *yes | + *yes | + *none | + *PNG + * metadata format | + *
| + * TIFF | + *yes | + *yes | + *+ * TIFF plug-in notes | + *+ * TIFF metadata format | + *
| + * WBMP | + *yes | + *yes | + *none | + *+ * WBMP metadata format | + *
+ * By default the GIF writer plug-in creates version "89a" images. This can be + * changed to "87a" by explicitly setting the version in the stream metadata + * (see + * + * GIF Stream Metadata Format Specification). + * + * + *
+ * The GIF writer plug-in supports the creation of animated GIF images through + * the standard sequence writing methods defined in the {@code ImageWriter} + * class. + * + * + * + * + *
+ * A global color table is written to the output stream if one of the following + * conditions is met: + *
+ * In the first case the global color table in the stream metadata is used, in + * the second the local color table in the image metadata is used, and in the + * third a global color table is created from the ColorModel or SampleModel of + * the (first) image. + *
+ * A local color table is written to the output stream only if image metadata + * containing a LocalColorTable element is supplied to the writer, or no image + * metadata is supplied to the writer and the local color table which would be + * generated from the image itself is not equal to the global color table. + *
+ * A Graphic Control Extension block is written to the output stream only if + * image metadata containing a GraphicControlExtension element is supplied to + * the writer, or no image metadata is supplied and the local color table + * generated from the image requires a transparent index. Application, Plain + * Text, and Comment Extension blocks are written only if they are supplied to + * the writer via image metadata. + * + * + *
+ * The writing of interlaced images can be controlled by the progressive mode of + * the provided {@code ImageWriteParam} instance. If progressive mode is + * {@code MODE_DISABLED} then a non-interlaced image will be written. If + * progressive mode is {@code MODE_DEFAULT} then an interlaced image will be + * written. If progressive mode is {@code MODE_COPY_FROM_METADATA}, then the + * metadata setting is used (if it is provided, otherwise an interlaced image + * will be written). + *
+ * The GIF image writer plug-in supports setting output stream metadata from + * metadata supplied to the writer in either the native GIF stream metadata + * format + * + * javax_imageio_gif_stream_1.0 or the standard metadata format + * javax_imageio_1.0, + * and setting output image metadata from metadata supplied to the writer in + * either the native GIF image metadata format + * + * javax_imageio_gif_image_1.0 or the standard metadata format + * javax_imageio_1.0. + * The mapping of standard metadata format to the GIF native stream and image + * metadata formats is given in the tables + * here. + * + * @since 1.4 + */ +package javax.imageio; diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/package.html b/jdk/src/java.desktop/share/classes/javax/imageio/package.html deleted file mode 100644 index 63d6dcfeb26..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/imageio/package.html +++ /dev/null @@ -1,253 +0,0 @@ - - -
- - - - - - -The main package of the Java Image I/O API. - -
-
-Many common image I/O operations may be performed using the static
-methods of the ImageIO class.
-
-
-
-This package contains the basic classes and interfaces for describing
-the contents of image files, including metadata and thumbnails
-(IIOImage); for controlling the image reading process
-(ImageReader, ImageReadParam, and
-ImageTypeSpecifier) and image writing process
-(ImageWriter and ImageWriteParam); for
-performing transcoding between formats (ImageTranscoder),
-and for reporting errors (IIOException).
-
-
-All implementations of javax.imageio provide the following standard -image format plug-ins: -
-| Reading | Writing | -Notes | Metadata | -|
|---|---|---|---|---|
| BMP | -yes | -yes | -none | -- BMP metadata format | -
| GIF | -yes | -yes | -- GIF plug-in notes | -- GIF metadata format | -
| JPEG | -yes | -yes | -none | -- JPEG metadata format | -
| PNG | -yes | -yes | -none | -- PNG metadata format | -
| TIFF | -yes | -yes | -- TIFF plug-in notes | -- TIFF metadata format | -
| WBMP | -yes | -yes | -none | -- WBMP metadata format | -
-ImageIO provides ImageReader and ImageWriter
-plug-ins for the
-Graphics Interchange Format (GIF) image format.
-
-These are the "standard" GIF plug-ins, meaning those that are included in the
-JRE, as distinct from those included in standard extensions, or 3rd party
-plug-ins. The following notes and metadata specification apply to the
-standard plug-ins.
-
-
- By default the GIF writer plug-in creates version "89a" images. This can be - changed to "87a" by explicitly setting the version in the - stream metadata (see - GIF Stream Metadata Format Specification). -
- - - -
- The GIF writer plug-in supports the creation of animated GIF images through
- the standard sequence writing methods defined in the
- ImageWriter class.
-
-
-
- A global color table is written to the output stream if one of the - following conditions is met: -
- In the first case the global color table in the stream metadata is - used, in the second the local color table in the image metadata is - used, and in the third a global color table is created from the - ColorModel or SampleModel of the (first) image. -
- -- A local color table is written to the output stream only if image - metadata containing a LocalColorTable element is supplied to the - writer, or no image metadata is supplied to the writer and the local - color table which would be generated from the image itself is not - equal to the global color table. -
- -- A Graphic Control Extension block is written to the output stream only - if image metadata containing a GraphicControlExtension element is - supplied to the writer, or no image metadata is supplied and the - local color table generated from the image requires a transparent - index. Application, Plain Text, and Comment Extension blocks are - written only if they are supplied to the writer via image metadata. - -
- - -
-
- The writing of interlaced images can be controlled by the progressive
- mode of the provided ImageWriteParam instance.
- If progressive mode is
- MODE_DISABLED then a non-interlaced image will be written. If
- progressive mode is MODE_DEFAULT then an interlaced image will
- be written. If progressive mode is MODE_COPY_FROM_METADATA, then
- the metadata setting is used (if it is provided, otherwise an interlaced
- image will be written).
-
- The GIF image writer plug-in supports setting output stream metadata from - metadata supplied to the writer in either the native GIF stream - metadata format - javax_imageio_gif_stream_1.0 or the standard metadata format - - javax_imageio_1.0, and setting - output image metadata from metadata supplied to the writer in either - the native GIF image metadata format - javax_imageio_gif_image_1.0 or the standard metadata format - javax_imageio_1.0. - - The mapping of standard metadata format to the GIF native stream and - image metadata formats is given in the tables here . -
- - - - -@since 1.4 - - diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/bmp/package-info.java b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/bmp/package-info.java new file mode 100644 index 00000000000..d423a14321d --- /dev/null +++ b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/bmp/package-info.java @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2003, 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Package containing the public classes used by the built-in BMP plug-in. + * + * @since 1.5 + */ +package javax.imageio.plugins.bmp; diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/bmp/package.html b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/bmp/package.html deleted file mode 100644 index 36467da7f5f..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/bmp/package.html +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - - - - -Package containing the public classes used by the built-in BMP plug-in. - -@since 1.5 - - diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/jpeg/package-info.java b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/jpeg/package-info.java new file mode 100644 index 00000000000..cd437729871 --- /dev/null +++ b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/jpeg/package-info.java @@ -0,0 +1,40 @@ +/* + * 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Classes supporting the built-in JPEG plug-in. + *+ * This package contains some support classes for the built-in JPEG reader and + * writer plug-ins. Classes are provided for representing quantization and + * Huffman tables, and extensions of {@code ImageReadParam} and + * {@code ImageWriteParam} are provided to supply tables during the reading and + * writing process. For more information about the operation of the built-in + * JPEG plug-ins, see the + * JPEG metadata format + * specification and usage notes. + * + * @since 1.4 + */ +package javax.imageio.plugins.jpeg; diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/jpeg/package.html b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/jpeg/package.html deleted file mode 100644 index 60d4e8eeaf4..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/jpeg/package.html +++ /dev/null @@ -1,69 +0,0 @@ - - -
- - - - - - -Classes supporting the built-in JPEG plug-in. - -
-
-This package contains some support classes for the built-in JPEG
-reader and writer plug-ins. Classes are provided for representing
-quantization and Huffman tables, and extensions of
-ImageReadParam and ImageWriteParam are
-provided to supply tables during the reading and writing process. For
-more information about the operation of the built-in JPEG plug-ins,
-see the JPEG
-metadata format specification and usage notes.
-
-
-
-
-
-
-
-@since 1.4
-
-
diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/tiff/package-info.java b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/tiff/package-info.java
new file mode 100644
index 00000000000..80defcc7a12
--- /dev/null
+++ b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/tiff/package-info.java
@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2005, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * Public classes used by the built-in TIFF plug-ins.
+ *
+ * This package contains classes supporting the built-in TIFF reader and writer + * plug-ins. Classes are provided for simplifying interaction with metadata, + * including Exif metadata common in digital photography, and an extension of + * {@link javax.imageio.ImageReadParam} which permits specifying which metadata + * tags are allowed to be read. For more information about the operation of the + * built-in TIFF plug-ins, see the + * TIFF metadata format + * specification and usage notes. + * + * @since 9 + */ +package javax.imageio.plugins.tiff; diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/tiff/package.html b/jdk/src/java.desktop/share/classes/javax/imageio/plugins/tiff/package.html deleted file mode 100644 index 7c70425fd08..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/imageio/plugins/tiff/package.html +++ /dev/null @@ -1,49 +0,0 @@ - - -
- - - - -Public classes used by the built-in TIFF plug-ins. - -
-This package contains classes supporting the built-in TIFF reader and writer
-plug-ins. Classes are provided for simplifying interaction with metadata,
-including Exif metadata common in digital photography, and an extension of
-{@link javax.imageio.ImageReadParam} which permits specifying which metadata
-tags are allowed to be read. For more information about the operation of the
-built-in TIFF plug-ins, see the
-TIFF metadata format
-specification and usage notes.
-
-
-
-
-
-@since 9
-
-
diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/spi/package-info.java b/jdk/src/java.desktop/share/classes/javax/imageio/spi/package-info.java
new file mode 100644
index 00000000000..bdaf57c698f
--- /dev/null
+++ b/jdk/src/java.desktop/share/classes/javax/imageio/spi/package-info.java
@@ -0,0 +1,38 @@
+/*
+ * 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * A package of the Java Image I/O API containing the plug-in interfaces for
+ * readers, writers, transcoders, and streams, and a runtime registry.
+ *
+ * The {@code javax.imageio.spi} package contains service provider interfaces + * for reading, writing, and transcoding images, and obtaining image input and + * output streams, as well as a run-time registry that discovers installed + * instances of Image I/O service providers and allows new instances to be + * registered dynamically. + * + * @since 1.4 + */ +package javax.imageio.spi; diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/spi/package.html b/jdk/src/java.desktop/share/classes/javax/imageio/spi/package.html deleted file mode 100644 index 404e0a66289..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/imageio/spi/package.html +++ /dev/null @@ -1,48 +0,0 @@ - - -
- - - - - - -A package of the Java Image I/O API containing the plug-in interfaces -for readers, writers, transcoders, and streams, and a runtime -registry. - -
-
-
-The javax.imageio.spi package contains service
-provider interfaces for reading, writing, and transcoding images, and
-obtaining image input and output streams, as well as a run-time registry
-that discovers installed instances of Image I/O service providers and allows new
-instances to be registered dynamically.
-
-@since 1.4
-
-
diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/stream/package-info.java b/jdk/src/java.desktop/share/classes/javax/imageio/stream/package-info.java
new file mode 100644
index 00000000000..b28caf0ef0d
--- /dev/null
+++ b/jdk/src/java.desktop/share/classes/javax/imageio/stream/package-info.java
@@ -0,0 +1,50 @@
+/*
+ * 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * A package of the Java Image I/O API dealing with low-level I/O from files and
+ * streams.
+ *
+ * The {@code ImageInputStream} interface unifies streaming and file-based + * operations. An abstract base class, {@code ImageInputStreamImpl} is provided + * to simplify writing a new {@code ImageInputStream} class. Concrete + * implementation classes ({@code FileImageInputStream}, + * {@code FileCacheImageInputStream}, and {@code MemoryCacheImageInputStream}) + * are provided that allow input to come from a {@code File} or + * {@code InputStream} with or without the use of a temporary cache file. + *
+ * The {@code ImageOutputStream} interface performs an analogous function for + * output. An abstract base class, {@code ImageOutputStreamImpl} is provided, + * along with concrete implementation classes ({@code FileImageOutputStream}, + * {@code FileCacheImageOutputStream}, and {@code MemoryCacheImageOutputStream}) + * are provided that allow output to go to a {@code File} or + * {@code OutputStream} with or without the use of a temporary cache file. + *
+ * The {@code IIOByteBuffer} class provides an alternative way to perform reads + * of sequences of bytes that reduces the amount of internal data copying. + * + * @since 1.4 + */ +package javax.imageio.stream; diff --git a/jdk/src/java.desktop/share/classes/javax/imageio/stream/package.html b/jdk/src/java.desktop/share/classes/javax/imageio/stream/package.html deleted file mode 100644 index 41f84b8fb61..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/imageio/stream/package.html +++ /dev/null @@ -1,67 +0,0 @@ - - -
- - - - - - -A package of the Java Image I/O API dealing with low-level I/O from -files and streams. - -
-
-The ImageInputStream interface unifies streaming and
-file-based operations. An abstract base class,
-ImageInputStreamImpl is provided to simplify writing
-a new ImageInputStream class. Concrete implementation
-classes (FileImageInputStream,
-FileCacheImageInputStream, and
-MemoryCacheImageInputStream) are provided that allow
-input to come from a File or InputStream
-with or without the use of a temporary cache file.
-
-
-
-The ImageOutputStream interface performs an analogous
-function for output. An abstract base class,
-ImageOutputStreamImpl is provided, along with
-concrete implementation classes (FileImageOutputStream,
-FileCacheImageOutputStream, and
-MemoryCacheImageOutputStream) are provided that allow
-output to go to a File or OutputStream with
-or without the use of a temporary cache file.
-
-
-
-The IIOByteBuffer class provides an alternative way to
-perform reads of sequences of bytes that reduces the amount of
-internal data copying.
-
-@since 1.4
-
-
diff --git a/jdk/src/java.desktop/share/classes/javax/print/attribute/package-info.java b/jdk/src/java.desktop/share/classes/javax/print/attribute/package-info.java
new file mode 100644
index 00000000000..f9c571f56c0
--- /dev/null
+++ b/jdk/src/java.desktop/share/classes/javax/print/attribute/package-info.java
@@ -0,0 +1,376 @@
+/*
+ * 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * Provides classes and interfaces that describe the types of Java™ Print
+ * Service attributes and how they can be collected into attribute sets.
+ *
+ *
+ * The print data and the processing instructions are separate entities. This + * means that: + *
+ * The processing instruction does not specify how the print job processes the + * request; each processing instruction is only a description of the results of + * a print job. The print job determines the manner in which it achieves the + * results specified by the processing instructions. Representing processing + * instructions as descriptive items provides more flexibility for implementing + * print jobs. + * + *
+ * In the Java Print Service API, an attribute category is represented by a Java + * class implementing the Attribute interface. + * Attribute values are instances of such a class or one of its subclasses. For + * example, to specify the number of copies, an application constructs an + * instance of the Copies class with the + * number of desired copies and uses the {@code Copies} instance as part of the + * print request. In this case, the {@code Copies} class represents the + * attribute category, and the {@code Copies} instance represents the attribute + * value. + * + *
+ * Once the printer starts processing the print job, additional information + * about the job becomes available, which might include: the job state (such as + * completed or queued) and the number of pages printed so far. + * These pieces of information are also attributes. Attributes can also describe + * the printer itself, such as: the printer name, the printer location, and the + * number of jobs queued. + *
+ * The Java Print Service API defines these different kinds of attributes with + * five subinterfaces of {@code Attribute}: + *
+ * The Java Print Service API defines a group of standard attribute classes + * modeled upon the attributes in the Internet Printing Protocol (IPP) version + * 1.1. The standard attribute classes are in the subpackage + * javax.print.attribute.standard to keep the actual attribute classes + * conceptually separate from the generic apparatus defined in package + * javax.print.attribute. + * + *
+ * The {@code AttributeSet} interface is similar to the + * Map interface: it provides a map of + * key to values, in which each key is unique and can contain no more than one + * value. However, the {@code AttributeSet} interface is designed to + * specifically support the needs of the Java Print Service API. An {@code + * AttributeSet} requires that: + *
+ * The javax.print.attribute package includes + * HashAttributeSet as a concrete + * implementation of the attribute set interface. {@code HashAttributeSet} + * provides an attribute set based on a hash map. You can use this + * implementation or provide your own implementation of interface + * {@code AttributeSet}. + *
+ * The Java Print Service API provides four specializations of an attribute set + * that are restricted to contain just one of the four kinds of attributes, as + * discussed in the Attribute Roles section: + *
+ * In some contexts, an attribute set is read-only, which means that the client + * is only allowed to examine an attribute set's contents but not change them. + * In other contexts, the attribute set is read-write, which means that the + * client is allowed both to examine and to change an attribute set's contents. + * For a read-only attribute set, calling a mutating operation throws an + * {@code UnmodifiableSetException}. + *
+ * Package javax.print.attribute includes one concrete implementation of each of + * the attribute set subinterfaces: + *
+ * Even though the Java Print Service API includes a large number of different + * attribute categories, there are only a few different types of attribute + * values. Most attributes can be represented by a small number of data types, + * such as: integer values, integer ranges, text, or an enumeration of integer + * values. The type of the attribute value that a category accepts is called the + * attribute's abstract syntax. To provide consistency and reduce code + * duplication, the Java Print Service API defines abstract syntax classes to + * represent each abstract syntax, and these classes are used as the parent of + * standard attributes whenever possible. The abstract syntax classes are: + *
+ * Each attribute class implements the {@code Attribute} interface, either + * directly or indirectly, to mark it as a printing attribute. An attribute + * class that can appear in restricted attribute sets in certain contexts also + * implements one or more subinterfaces of {@code Attribute}. Most attribute + * classes also extend the appropriate abstract syntax class to get the + * implementation. Consider the {@code Sides} attribute class: + *
+ * {@code
+ * public class Sides
+ * extends EnumSyntax
+ * implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
+ * {
+ * public final Object getCategory()
+ * {
+ * return Sides.class;
+ * }
+ * ...
+ * }}
+ *
+ *
+ * + * Since every attribute class implements {@code Attribute}, every attribute + * class must provide an implementation for the + * {@link javax.print.attribute.Attribute#getCategory() getCategory} method, + * which returns the attribute category. In the case of {@code Sides}, the + * {@code getCategory} method returns {@code Sides.class}. The + * {@code getCategory} method is final to ensure that any vendor-defined + * subclasses of a standard attribute class appear in the same category. Every + * attribute object is immutable once constructed so that attribute object + * references can be passed around freely. To get a different attribute value, + * construct a different attribute object. + * + *
+ * To define a new attribute category, a vendor defines a new attribute class. + * This attribute class, like the standard attribute classes, implements + * {@code Attribute} or one of its subinterfaces and extends an abstract syntax + * class. The vendor can either use an existing abstract syntax class or define + * a new one. The new vendor-defined attribute can be used wherever an + * {@code Attribute} is used, such as in an {@code AttributeSet}. + * + *
+ * {@code
+ * FileInputStream psStream;
+ * try {
+ * psstream = new FileInputStream("file.ps");
+ * } catch (FileNotFoundException ffne) {
+ * }
+ * if (psstream == null) {
+ * return;
+ * }
+ * //Set the document type. See the DocFlavor documentation for
+ * //more information.
+ * DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
+ * Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
+ * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
+ * aset.add(new Copies(5));
+ * aset.add(MediaSize.A4);
+ * aset.add(Sides.DUPLEX);
+ * PrintService[] services =
+ * PrintServiceLookup.lookupPrintServices(psInFormat, aset);
+ * if (services.length > 0) {
+ * DocPrintJob job = services[0].createPrintJob();
+ * try {
+ * job.print(myDoc, aset);
+ * } catch (PrintException pe) {}
+ * }
+ * }
+ *
+ * + * Please note: In the javax.print APIs, a null reference parameter to methods + * is incorrect unless explicitly documented on the method as having a + * meaningful interpretation. Usage to the contrary is incorrect coding and may + * result in a run time exception either immediately or at some later time. + * IllegalArgumentException and NullPointerException are examples of typical and + * acceptable run time exceptions for such cases. + * + * @since 1.4 + */ +package javax.print.attribute; diff --git a/jdk/src/java.desktop/share/classes/javax/print/attribute/package.html b/jdk/src/java.desktop/share/classes/javax/print/attribute/package.html deleted file mode 100644 index aeedb0df2c2..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/print/attribute/package.html +++ /dev/null @@ -1,404 +0,0 @@ - - -
--The print data and the processing instructions -are separate entities. This means that: -
- -The processing instruction does not specify how the print job -processes the request; each processing instruction is only a description -of the results of a print job. The print job determines the manner in -which it achieves the results specified by the processing instructions. -Representing processing instructions as descriptive items -provides more flexibility for implementing print jobs. -
-In the Java Print Service API, an attribute category is represented by a Java
-class implementing the Attribute interface.
-Attribute values are instances of such a class or
-one of its subclasses. For example, to specify the number of copies, an
-application constructs an instance of the
-Copies class with the
-number of desired copies and uses the Copies instance as part of
-the print request. In this case, the Copies class represents the
-attribute category, and the Copies instance represents the
-attribute value.
-
-
-Once the printer starts processing the print job, -additional information about the job becomes available, which might include: -the job state (such as completed or queued) and -the number of pages printed so far. These pieces of information are also -attributes. Attributes can also describe the printer itself, such as: -the printer name, the printer location, and the number of jobs queued. -
-
-The Java Print Service API defines these different kinds of attributes
-with five subinterfaces of Attribute:
-
DocAttribute
-or to an entire print job as a PrintRequestAttribute.
-Certain low-level attributes
-are never used on their own
-but are always aggregated into higher-level attributes.
-These low-level attribute classes only
-implement interface Attribute,
-not any of the tagging subinterfaces.
--The Java Print Service API defines a group of -standard attribute classes modeled upon the attributes in -the Internet Printing Protocol (IPP) version 1.1. The -standard attribute classes are in the subpackage -javax.print.attribute.standard to keep the actual -attribute classes conceptually separate from the generic -apparatus defined in package javax.print.attribute. - -
-The AttributeSet interface is similar to the
-Map interface: it provides a map of
-key to values, in which each key is unique and can contain no more than one
-value. However, the AttributeSet interface is designed to
-specifically support the needs of the Java Print Service API. An
-AttributeSet requires that:
-
AttributeSet corresponds to a category, and
-the value of the key can only be one of the attribute values that belong
-to the category represented by the key. Thus, unlike a Map, an
-AttributeSet restricts the possible values of a key: an
-attribute category cannot be set to an attribute value that does not belong to
-that category.
-Attribute interface can
-be added to the set.
-
-The javax.print.attribute package includes
-HashAttributeSet
-as a concrete implementation of the attribute set interface.
-HashAttributeSet provides an attribute set based on a hash map.
-You can use this implementation or provide your own implementation
-of interface AttributeSet.
-
-The Java Print Service API provides four specializations of an attribute set -that are restricted to contain just one of the four kinds of attributes, -as discussed in the Attribute Roles section: -
-Notice that only four kinds of attribute sets are listed here, but there are -five kinds of attributes. Interface -SupportedValuesAttribute -denotes an attribute that gives the supported values for another attribute. -Supported-values attributes are never aggregated into attribute sets, -so there is no attribute set subinterface defined for them. - -
-In some contexts, an attribute set is read-only, which means that the
-client is only allowed to examine an attribute set's
-contents but not change them. In other contexts, the attribute set is read-write,
-which means that the client is allowed both to examine and to change an
-attribute set's contents. For a read-only attribute set, calling a mutating
-operation throws an UnmodifiableSetException.
-
-Package javax.print.attribute includes -one concrete implementation of each of the attribute set subinterfaces: -
Copies, class Sides, and class
-PrinterResolution. Each
-attribute class wraps one or more primitive data items containing the
-attribute's value. Attribute set operations perform frequent
-comparisons between attribute category objects when adding attributes,
-finding existing attributes in the same category, and looking
-up an attribute given its category. Because an attribute category is
-represented by a class, fast attribute-value comparisons can be performed
-with the Class.equals method.
--Even though the Java Print Service API includes a large number of -different attribute categories, there are only a few different types -of attribute values. Most attributes can be represented by a small -number of data types, such as: integer values, integer ranges, text, -or an enumeration of integer values. The type of the attribute value that -a category accepts is called the attribute's abstract syntax. To -provide consistency and reduce code duplication, the Java Print Service -API defines abstract syntax classes to represent each -abstract syntax, and these classes are used as the parent of standard -attributes whenever possible. The abstract syntax classes are: -
-Each attribute class implements the Attribute interface, either
-directly or indirectly, to mark it as a printing attribute. An
-attribute class that can appear in restricted attribute sets in
-certain contexts also implements one or more subinterfaces of
-Attribute. Most attribute classes also extend the appropriate
-abstract syntax class to get the implementation. Consider the
-Sides attribute class:
-
-
-public class Sides
- extends EnumSyntax
- implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
- {
- public final Object getCategory()
- {
- return Sides.class;
- }
- ...
- }
-
-
-
-Since every attribute class implements Attribute, every attribute
-class must provide an implementation for the
-{@link javax.print.attribute.Attribute#getCategory() getCategory} method,
-which returns the attribute category. In the case of Sides, the
-getCategory method returns Sides.class. The
-getCategory method is final to ensure that any vendor-defined
-subclasses of a standard attribute class appear in the same category.
-Every attribute object is immutable once constructed so that attribute object
-references can be passed around freely. To get a different attribute
-value, construct a different attribute object.
-
-
EnumSyntax specifies all the possible attribute values
-at compile time as singleton instances of the attribute class. This
-means that new enumerated values cannot be constructed at run time.
-To define new vendor-specific values for a standard enumerated
-attribute, the vendor must define a new attribute class specifying
-the new singleton instances. To ensure that the new attribute values
-fall in the same category as the standard attribute values, the new
-attribute class must be a subclass of the standard attribute class.
-
-To define a new attribute category, a vendor defines a new attribute
-class. This attribute class, like the standard attribute classes,
-implements Attribute or one of its subinterfaces and extends an
-abstract syntax class. The vendor can either use an existing
-abstract syntax class or define a new one. The new vendor-defined
-attribute can be used wherever an Attribute is used, such as in an
-AttributeSet.
-
-
PrintRequestAttributeSet
-because print-request attributes are the types of attributes that
-client usually specifies. This example demonstrates creating an attribute
-set of print-request attributes and locating a printer that can
-print the document according to the specified attributes:
-
-
-
-FileInputStream psStream;
-try {
- psstream = new FileInputStream("file.ps");
-} catch (FileNotFoundException ffne) {
-}
-if (psstream == null) {
- return;
-}
-//Set the document type. See the DocFlavor documentation for
-//more information.
-DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
-Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
-PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
-aset.add(new Copies(5));
-aset.add(MediaSize.A4);
-aset.add(Sides.DUPLEX);
-
-PrintService[] services =
- PrintServiceLookup.lookupPrintServices(psInFormat, aset);
-if (services.length > 0) {
- DocPrintJob job = services[0].createPrintJob();
- try {
- job.print(myDoc, aset);
- } catch (PrintException pe) {}
-}
-
-
--Please note: In the javax.print APIs, a null reference parameter to methods -is incorrect unless explicitly documented on the method as having a meaningful -interpretation. Usage to the contrary is incorrect coding and may result -in a run time exception either immediately or at some later time. -IllegalArgumentException and NullPointerException are examples of -typical and acceptable run time exceptions for such cases. - -@since 1.4 - - diff --git a/jdk/src/java.desktop/share/classes/javax/print/attribute/standard/package-info.java b/jdk/src/java.desktop/share/classes/javax/print/attribute/standard/package-info.java new file mode 100644 index 00000000000..1e44ec9af61 --- /dev/null +++ b/jdk/src/java.desktop/share/classes/javax/print/attribute/standard/package-info.java @@ -0,0 +1,637 @@ +/* + * 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Package javax.print.attribute.standard contains classes for specific printing + * attributes. The parent package, + * javax.print.attribute, provides classes and interfaces that describe the + * types of Java Print Service attributes and how they can be collected into + * attribute sets. + *
+ * An attribute represents a printing feature that a print service can provide. + * For each attribute, a print service either does or does not support the + * attribute. For each possible value of a supported attribute, a print service + * either does or does not support the value. + *
+ * The API requires every print service to support certain attributes; other + * attributes are optional and the service can choose whether or not to support + * them. Each attribute has a set of values that it accepts. The API requires + * every print service to support certain values for certain attributes; other + * attribute values are optional and the service can choose whether or not to + * support them. These support requirements are recorded in the documentation + * for each attribute class. + *
+ * Package javax.print.attribute.standard contains standard printing attributes + * and standard printing attribute values that are widely used in the printing + * domain. A print service vendor can provide new vendor-specific printing + * attributes in addition to the standard ones. A vendor can also provide + * vendor-specific extensions (subclasses) of the standard printing attributes + * -- for example, to provide additional vendor-specific values for an existing + * standard attribute. Of course, if a vendor wants clients to be able to use + * any added or extended attributes, the vendor must publish the new attribute + * classes. + *
+ * Many of the standard attribute classes extend one of the abstract syntax + * classes of the javax.print.attribute package. These abstract syntax classes + * each represent a different type. The + * EnumSyntax class, for example, represents a type-safe enumeration. The + * abstract syntax class provides a wrapper for the attribute value. + *
+ * If an attribute class extends {@code EnumSyntax}, and the value of the + * attribute is an IPP-compatible value, the attribute's {@code toString} method + * returns the IPP string representation of the attribute value, such as + * "processing-stopped" for the JobState attribute. + * However, because the {@code EnumSyntax} class is extensible, vendors can + * define their own attribute values. If an attribute uses the + * {@code EnumSyntax} class and is set to one of these vendor-defined values + * then the {@code toString} method will not return the IPP string + * representation of the value. + *
+ * A printing client application will typically not need to use all the printing + * attribute classes in package javax.print.attribute.standard, just the ones + * that pertain to the application. + *
+ * The attribute classes in package javax.print.attribute.standard are based on + * the Internet Printing Protocol (IPP) attributes as defined in the Internet + * RFC document, RFC 2911 Internet Printing Protocol/1.1: Model and + * Semantics dated September 2000. See + * RFC 2911 for more + * information. The descriptive text for each attribute class was taken largely + * from the above documents. The above authors' contribution to the API is + * gratefully acknowledged. + * + *
+ * Some attributes are doc attributes but not print request attributes and may + * only be specified at the doc level. Some attributes are print request + * attributes but not doc attributes and may only be specified at the Print + * Request level. Some attributes are both doc attributes and print request + * attributes and may be specified either at the doc level or at the Print + * Request level. + *
+ * When specified at the doc level, an attribute applies just to that one doc. + * When specified at the Print Request level, an attribute applies to the whole + * job, including all the docs in the job. However, an attribute specified at + * the doc level overrides an attribute in the same category specified at the + * Print Request level. + * + *
+ * Some attributes are both print request attributes and print job attributes; a + * client may include such attributes in a Print Request to specify + * characteristics for the ensuing Print Job, and those attributes then also + * appear in the Print Job's attribute set. Some attributes are print job + * attributes but not print request attributes; the print service itself adds + * these attributes to the Print Job's attribute set. + * + *
| Attribute Class | + *Doc Attribute |
+ * Print Request Attribute |
+ * Print Job Attribute |
+ * Print Service Attribute |
+ * SupportedValuesAttribute | + *
|---|---|---|---|---|---|
| Compression | + *X | + *+ * | + * | + * | + * |
| DocumentName | + *X | + *+ * | + * | + * | + * |
| Chromaticity | + *X | + *X | + *X | + *+ * | + * |
| Copies | + *+ * | X | + *X | + *+ * | CopiesSupported | + *
| Finishings | + *X | + *X | + *X | + *+ * | + * |
| JobHoldUntil | + *+ * | X | + *X | + *+ * | + * |
| JobImpressions | + *+ * | X | + *X | + *+ * | + * JobImpressionsSupported | + *
| JobKOctets | + *+ * | X | + *X | + *+ * | JobKOctetsSupported | + *
| JobMediaSheets | + *+ * | X | + *X | + *+ * | + * JobMediaSheetsSupported | + *
| JobName | + *+ * | X | + *X | + *+ * | + * |
| JobPriority | + *+ * | X | + *X | + *+ * | JobPrioritySupported | + *
| JobSheets | + *+ * | X | + *X | + *+ * | + * |
| Media | + *X | + *X | + *X | + *+ * | + * |
| MediaSize | + *+ * | + * | + * | + * | + * |
| + * MultipleDocumentHandling | + *+ * | X | + *X | + *+ * | + * |
| NumberUp | + *X | + *X | + *X | + *+ * | NumberUpSupported | + *
| OrientationRequested | + *X | + *X | + *X | + *+ * | + * |
| PageRanges | + *X | + *X | + *X | + *+ * | + * |
| + * PresentationDirection | + *X | + *X | + *X | + *+ * | + * |
| PrinterResolution | + *X | + *X | + *X | + *+ * | + * |
| PrintQuality | + *X | + *X | + *X | + *+ * | + * |
| RequestingUserName | + *+ * | X | + *X | + *+ * | + * |
| SheetCollate | + *X | + *X | + *X | + *+ * | + * |
| Sides | + *X | + *X | + *X | + *+ * | + * |
| DateTimeAtCompleted | + *+ * | + * | X | + *+ * | + * |
| DateTimeAtCreation | + *+ * | + * | X | + *+ * | + * |
| DateTimeAtProcessing | + *+ * | + * | X | + *+ * | + * |
| + * JobImpressionsCompleted | + *+ * | + * | X | + *+ * | + * |
| JobKOctetsProcessed | + *+ * | + * | X | + *+ * | + * |
| + * JobMediaSheetsCompleted | + *+ * | + * | X | + *+ * | + * |
| + * JobMessageFromOperator | + *+ * | + * | X | + *+ * | + * |
| + * JobOriginatingUserName | + *+ * | + * | X | + *+ * | + * |
| JobState | + *+ * | + * | X | + *+ * | + * |
| JobStateReasons + * Contains zero or more -- |
+ * + * | + * | X | + *+ * | + * |
| -- JobStateReason | + *+ * | + * | + * | + * | + * |
| NumberOfDocuments | + *+ * | + * | X | + *+ * | + * |
| + * NumberOfInterveningJobs | + *+ * | + * | X | + *+ * | + * |
| OutputDeviceAssigned | + *+ * | + * | X | + *+ * | + * |
| ColorSupported | + *+ * | + * | + * | X | + *+ * |
| PagesPerMinute | + *+ * | + * | + * | X | + *+ * |
| PagesPerMinuteColor | + *+ * | + * | + * | X | + *+ * |
| PDLOverrideSupported | + *+ * | + * | + * | X | + *+ * |
| + * PrinterIsAcceptingJobs | + *+ * | + * | + * | X | + *+ * |
| PrinterInfo | + *+ * | + * | + * | X | + *+ * |
| PrinterLocation | + *+ * | + * | + * | X | + *+ * |
| + * PrinterMessageFromOperator | + *+ * | + * | + * | X | + *+ * |
| PrinterMakeAndModel | + *+ * | + * | + * | X | + *+ * |
| PrinterMoreInfo | + *+ * | + * | + * | X | + *+ * |
| + * PrinterMoreInfoManufacturer | + *+ * | + * | + * | X | + *+ * |
| PrinterName | + *+ * | + * | + * | X | + *+ * |
| PrinterState | + *+ * | + * | + * | X | + *+ * |
| PrinterStateReasons + * Contains zero or more -- |
+ * + * | + * | + * | X | + *+ * |
| -- PrinterStateReason | + *+ * | + * | + * | + * | + * |
| -- Severity | + *+ * | + * | + * | + * | + * |
| QueuedJobCount | + *+ * | + * | + * | X | + *+ * |
| + * ReferenceUriSchemesSupported | + *+ * | + * | + * | + * | + * |
+ * Please note: In the javax.print APIs, a null reference parameter to methods + * is incorrect unless explicitly documented on the method as having a + * meaningful interpretation. Usage to the contrary is incorrect coding and may + * result in a run time exception either immediately or at some later time. + * IllegalArgumentException and NullPointerException are examples of typical and + * acceptable run time exceptions for such cases. + * + * @since 1.4 + */ +package javax.print.attribute.standard; diff --git a/jdk/src/java.desktop/share/classes/javax/print/attribute/standard/package.html b/jdk/src/java.desktop/share/classes/javax/print/attribute/standard/package.html deleted file mode 100644 index 78d29368527..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/print/attribute/standard/package.html +++ /dev/null @@ -1,292 +0,0 @@ - - -
--An attribute represents a printing feature -that a print service can provide. -For each attribute, -a print service either does or does not support the attribute. -For each possible value of a supported attribute, -a print service either does or does not support the value. -
-The API requires every print service -to support certain attributes; -other attributes are optional -and the service can choose whether or not to support them. -Each attribute has a set of values that it accepts. The API -requires every print service to support certain values for -certain attributes; -other attribute values are optional -and the service can choose whether or not to support them. -These support requirements are recorded in the documentation -for each attribute class. -
-Package javax.print.attribute.standard -contains standard printing attributes -and standard printing attribute values -that are widely used in the printing domain. -A print service vendor -can provide new vendor-specific printing attributes -in addition to the standard ones. -A vendor can also provide -vendor-specific extensions (subclasses) -of the standard printing attributes -- -for example, -to provide additional vendor-specific values -for an existing standard attribute. -Of course, -if a vendor wants clients -to be able to use any added or extended attributes, -the vendor must publish the new attribute classes. -
-Many of the standard attribute classes extend one of -the abstract syntax classes of the javax.print.attribute package. -These abstract syntax classes each represent a -different type. The -EnumSyntax class, for example, represents a type-safe -enumeration. The abstract syntax class provides a wrapper for the attribute -value. -
-If an attribute class extends EnumSyntax, and the value of the
-attribute is an IPP-compatible value, the attribute's toString
-method returns the IPP string representation of the attribute value, such as
-"processing-stopped" for the
-JobState attribute. However, because the
-EnumSyntax class is extensible, vendors can define their own
-attribute values. If an attribute uses the EnumSyntax class
-and is set to one of these vendor-defined values then the toString
- method will not return the IPP string representation of the value.
-
-A printing client application -will typically not need to use -all the printing attribute classes -in package javax.print.attribute.standard, -just the ones that pertain to the application. -
-The attribute classes in package javax.print.attribute.standard -are based on the Internet Printing Protocol (IPP) attributes -as defined in the Internet RFC document, -RFC 2911 Internet Printing Protocol/1.1: Model and Semantics -dated September 2000. -See RFC 2911 -for more information. -The descriptive text for each attribute class -was taken largely from the above documents. -The above authors' contribution to the API -is gratefully acknowledged. - -
-Some attributes are doc attributes -but not print request attributes -and may only be specified at the doc level. -Some attributes are print request attributes -but not doc attributes -and may only be specified at the Print Request level. -Some attributes are both doc attributes -and print request attributes -and may be specified either at the doc level -or at the Print Request level. -
-When specified at the doc level, -an attribute applies just to that one doc. -When specified at the Print Request level, -an attribute applies to the whole job, -including all the docs in the job. -However, an attribute specified at the doc level -overrides an attribute in the same category -specified at the Print Request level. - -
-Some attributes are both print request attributes -and print job attributes; -a client may include such attributes in a Print Request -to specify characteristics for the ensuing Print Job, -and those attributes then also appear -in the Print Job's attribute set. -Some attributes are print job attributes -but not print request attributes; -the print service itself -adds these attributes to the Print Job's attribute set. - -
-Please note: In the javax.print APIs, a null reference parameter to methods -is incorrect unless explicitly documented on the method as having a meaningful -interpretation. Usage to the contrary is incorrect coding and may result -in a run time exception either immediately or at some later time. -IllegalArgumentException and NullPointerException are examples of -typical and acceptable run time exceptions for such cases. - -@since 1.4 - - diff --git a/jdk/src/java.desktop/share/classes/javax/print/event/package-info.java b/jdk/src/java.desktop/share/classes/javax/print/event/package-info.java new file mode 100644 index 00000000000..ca65f565da9 --- /dev/null +++ b/jdk/src/java.desktop/share/classes/javax/print/event/package-info.java @@ -0,0 +1,41 @@ +/* + * 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Package javax.print.event contains event classes and listener interfaces. + *
+ * They may be used to monitor both print services (such as printers going + * on-line & off-line), and the progress of a specific print job. + *
+ * Please note: In the javax.print APIs, a null reference parameter to methods + * is incorrect unless explicitly documented on the method as having a + * meaningful interpretation. Usage to the contrary is incorrect coding and may + * result in a run time exception either immediately or at some later time. + * IllegalArgumentException and NullPointerException are examples of typical and + * acceptable run time exceptions for such cases. + * + * @since 1.4 + */ +package javax.print.event; diff --git a/jdk/src/java.desktop/share/classes/javax/print/event/package.html b/jdk/src/java.desktop/share/classes/javax/print/event/package.html deleted file mode 100644 index 6e49d8b4fda..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/print/event/package.html +++ /dev/null @@ -1,45 +0,0 @@ - - -
--They may be used to monitor both print services (such as printers going -on-line & off-line), and the progress of a specific print job. -
-Please note: In the javax.print APIs, a null reference parameter to methods -is incorrect unless explicitly documented on the method as having a meaningful -interpretation. Usage to the contrary is incorrect coding and may result -in a run time exception either immediately or at some later time. -IllegalArgumentException and NullPointerException are examples of -typical and acceptable run time exceptions for such cases. - -@since 1.4 - - diff --git a/jdk/src/java.desktop/share/classes/javax/print/package-info.java b/jdk/src/java.desktop/share/classes/javax/print/package-info.java new file mode 100644 index 00000000000..0cdc7643ec6 --- /dev/null +++ b/jdk/src/java.desktop/share/classes/javax/print/package-info.java @@ -0,0 +1,133 @@ +/* + * 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Provides the principal classes and interfaces for the Java™ Print + * Service API. The Java Print Service API enables client and server + * applications to: + *
+ * The JDK includes {@code PrintServiceLookup} implementations that can locate + * the standard platform printers. To locate other types of printers, such as + * IPP printers or JINI printers, a print-service provider can write + * implementations of {@code PrintServiceLookup}. The print-service provider can + * dynamically install these {@code PrintServiceLookup} implementations using + * the + * SPI JAR file specification. + * + *
+ * The {@code javax.print.attribute} package describes the types of attributes + * and how they can be collected into sets. The + * {@code javax.print.attribute.standard} package enumerates all of the standard + * attributes supported by the API, most of which are implementations of + * attributes specified in the IETF Specification, + * RFC 2911 Internet Printing + * Protocol, 1.1: Model and Semantics, dated September 2000. The attributes + * specified in {@code javax.print.attribute.standard} include common + * capabilities, such as: resolution, copies, media sizes, job priority, and + * page ranges. + * + *
+ * {@code
+ * FileInputStream psStream;
+ * try {
+ * psStream = new FileInputStream("file.ps");
+ * } catch (FileNotFoundException ffne) {
+ * }
+ * if (psStream == null) {
+ * return;
+ * }
+ * DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
+ * Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
+ * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
+ * aset.add(new Copies(5));
+ * aset.add(MediaSizeName.ISO_A4);
+ * aset.add(Sides.DUPLEX);
+ * PrintService[] services =
+ * PrintServiceLookup.lookupPrintServices(psInFormat, aset);
+ * if (services.length > 0) {
+ * DocPrintJob job = services[0].createPrintJob();
+ * try {
+ * job.print(myDoc, aset);
+ * } catch (PrintException pe) {}
+ * }
+ * }
+ *
+ * + * Please note: In the javax.print APIs, a null reference parameter to methods + * is incorrect unless explicitly documented on the method as having a + * meaningful interpretation. Usage to the contrary is incorrect coding and may + * result in a run time exception either immediately or at some later time. + * IllegalArgumentException and NullPointerException are examples of typical and + * acceptable run time exceptions for such cases. + * + * @since 1.4 + */ +package javax.print; diff --git a/jdk/src/java.desktop/share/classes/javax/print/package.html b/jdk/src/java.desktop/share/classes/javax/print/package.html deleted file mode 100644 index e306ac6d77c..00000000000 --- a/jdk/src/java.desktop/share/classes/javax/print/package.html +++ /dev/null @@ -1,147 +0,0 @@ - - -
--An application invokes the static methods of the abstract class -{@link javax.print.PrintServiceLookup PrintServiceLookup} to locate print -services that have the capabilities to satisfy the application's print -request. For example, to print a double-sided document, the application -first needs to find printers that have the double-sided printing capability. -
-The JDK includes PrintServiceLookup implementations that
-can locate the standard platform printers. To locate other types of printers,
-such as IPP printers or JINI printers, a print-service provider can write
-implementations of PrintServiceLookup. The print-service provider
-can dynamically install these PrintServiceLookup implementations
-using the
-
-SPI JAR file specification.
-
-
-The javax.print.attribute package describes the types of attributes and
-how they can be collected into sets. The javax.print.attribute.standard
-package enumerates all of the standard attributes supported by the API, most
-of which are implementations of attributes specified in the IETF Specification,
-
-RFC 2911 Internet Printing Protocol, 1.1: Model and Semantics, dated
-September 2000. The attributes specified in javax.print.attribute.standard
-include common capabilities, such as: resolution, copies, media sizes,
-job priority, and page ranges.
-
-
DocFlavor object
-consists of a MIME type, which describes the format, and a document
-representation class name that indicates how the document is delivered
-to the printer or output stream. An application uses the
-DocFlavor and an attribute set to find printers that can
-print the document type specified by the DocFlavor and have
-the capabilities specified by the attribute set.
-
-DocFlavor.DocFlavor and the attribute set.DocFlavor
-and the actual print data, which can take many forms including: a Postscript
-file, a JPEG image, a URL, or plain text.
-
-FileInputStream psStream;
-try {
- psStream = new FileInputStream("file.ps");
-} catch (FileNotFoundException ffne) {
-}
-if (psStream == null) {
- return;
-}
-
-DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
-Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
-PrintRequestAttributeSet aset =
- new HashPrintRequestAttributeSet();
-aset.add(new Copies(5));
-aset.add(MediaSizeName.ISO_A4);
-aset.add(Sides.DUPLEX);
-PrintService[] services =
- PrintServiceLookup.lookupPrintServices(psInFormat, aset);
-if (services.length > 0) {
- DocPrintJob job = services[0].createPrintJob();
- try {
- job.print(myDoc, aset);
- } catch (PrintException pe) {}
-}
-
-
--Please note: In the javax.print APIs, a null reference parameter to methods -is incorrect unless explicitly documented on the method as having a meaningful -interpretation. Usage to the contrary is incorrect coding and may result -in a run time exception either immediately or at some later time. -IllegalArgumentException and NullPointerException are examples of -typical and acceptable run time exceptions for such cases. - -@since 1.4 - - diff --git a/jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java b/jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java new file mode 100644 index 00000000000..6b9d0f18733 --- /dev/null +++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java @@ -0,0 +1,38 @@ +/* + * Copyright (c) 1999, 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + * Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI + * (Musical Instrument Digital Interface) data. + * + *