DocFlavor
encapsulates an object that specifies the format in
which print data is supplied to a DocPrintJob
. "Doc" is a short,
easy-to-pronounce term that means "a piece of print data." The print data
format, or "doc flavor", consists of two things:
Class.getName()
method. (Thus the
class name for byte[]
is "[B"
, for char[]
it is
"[C"
.)
DocPrintJob
obtains its print data by means of interface
Doc
. A Doc
object lets the DocPrintJob
determine
the doc flavor the client can supply. A Doc
object also lets the
DocPrintJob
obtain an instance of the doc flavor's representation
class, from which the DocPrintJob
then obtains the actual print data.
For client formatted print data, the client determines or knows the
print data format. For example the client may have a JPEG encoded image, a
URL
for HTML code, or a disk file containing plain text in some
encoding, possibly obtained from an external source, and requires a way to
describe the data format to the print service.
The doc flavor's representation class is a conduit for the JPS
DocPrintJob
to obtain a sequence of characters or bytes from the
client. The doc flavor's MIME type is one of the standard media types telling
how to interpret the sequence of characters or bytes. For a list of standard
media types, see the Internet Assigned Numbers Authority's (IANA's)
Media Types Directory
. Interface Doc
provides two utility operations,
getReaderForText
and
getStreamForBytes()
, to help a Doc
object's client extract client formatted print data.
For client formatted print data, the print data representation class is typically one of the following (although other representation classes are permitted):
char[]
) -- The print data consists of the
Unicode characters in the array.
String
-- The print data consists of the Unicode characters in
the string.
java.io.Reader
) -- The print
data consists of the Unicode characters read from the stream up to the
end-of-stream.
byte[]
) -- The print data consists of the bytes in
the array. The bytes are encoded in the character set specified by the doc
flavor's MIME type. If the MIME type does not specify a character set, the
default character set is US-ASCII.
java.io.InputStream
) -- The
print data consists of the bytes read from the stream up to the
end-of-stream. The bytes are encoded in the character set specified by the
doc flavor's MIME type. If the MIME type does not specify a character set,
the default character set is US-ASCII.
URL
) -- The print data
consists of the bytes read from the URL location. The bytes are encoded in
the character set specified by the doc flavor's MIME type. If the MIME type
does not specify a character set, the default character set is US-ASCII.
When the representation class is a URL
, the print service itself
accesses and downloads the document directly from its URL
address,
without involving the client. The service may be some form of network print
service which is executing in a different environment. This means you
should not use a URL
print data flavor to print a document at a
restricted URL
that the client can see but the printer cannot see.
This also means you should not use a URL
print data flavor to print
a document stored in a local file that is not available at a URL
accessible independently of the client. For example, a file that is not
served up by an HTTP server or FTP server. To print such documents, let the
client open an input stream on the URL
or file and use an input
stream data flavor.
charset
parameter, the Java Print Service instance assumes the
US-ASCII character set by default. This is in accordance with
RFC 2046, which says the
default character set is US-ASCII. Note that US-ASCII is a subset of UTF-8,
so in the future this may be widened if a future RFC endorses UTF-8 as the
default in a compatible manner.
Also note that this is different than the behaviour of the Java runtime when interpreting a stream of bytes as text data. That assumes the default encoding for the user's locale. Thus, when spooling a file in local encoding to a Java Print Service it is important to correctly specify the encoding. Developers working in the English locales should be particularly conscious of this, as their platform encoding corresponds to the default mime charset. By this coincidence that particular case may work without specifying the encoding of platform data.
Every instance of the Java virtual machine has a default character encoding determined during virtual-machine startup and typically depends upon the locale and charset being used by the underlying operating system. In a distributed environment there is no guarantee that two VM share the same default encoding. Thus clients which want to stream platform encoded text data from the host platform to a Java Print Service instance must explicitly declare the charset and not rely on defaults.
The preferred form is the official IANA primary name for an encoding.
Applications which stream text data should always specify the charset in the
mime type, which necessitates obtaining the encoding of the host platform for
data (eg files) stored in that platform's encoding. A CharSet
which
corresponds to this and is suitable for use in a mime-type for a
DocFlavor
can be obtained from
DocFlavor.
This may not always be
the primary IANA name but is guaranteed to be understood by this VM. For
common flavors, the pre-defined *HOST DocFlavors
may be used.
See character encodings for more information on the character encodings supported on the Java platform.
DocFlavors
. However, here are some examples of MIME types that a Java
Print Service instance might support for client formatted print data. Nested
classes inside class DocFlavor
declare predefined static constant
DocFlavor
objects for these example doc flavors; class
DocFlavor
's constructor can be used to create an arbitrary doc
flavor.
MIME-Type | Description |
---|---|
"text/plain"
| Plain text in the default character set (US-ASCII) |
"text/plain; charset=xxx"
| Plain text in character set xxx |
"text/html"
| HyperText Markup Language in the default character set (US-ASCII) |
"text/html; charset=xxx"
| HyperText Markup Language in character set xxx |
MIME-Type | Description |
---|---|
"application/pdf"
| Portable Document Format document |
"application/postscript"
| PostScript document |
"application/vnd.hp-PCL"
| Printer Control Language document |
InputStream
, URL
).
MIME-Type | Description |
---|---|
"image/gif"
| Graphics Interchange Format image |
"image/jpeg"
| Joint Photographic Experts Group image |
"image/png"
| Portable Network Graphics image |
InputStream
, URL
).
MIME-Type | Description |
---|---|
"application/octet-stream"
| The print data format is unspecified (just an octet stream) |
InputStream
, URL
).
DocPrintJob
invokes to
determine the content to be printed -- such as a renderable image interface
or a Java printable interface. The doc flavor's MIME type is the special
value "application/x-java-jvm-local-objectref"
indicating the client
will supply a reference to a Java object that implements the interface named
as the representation class. This MIME type is just a placeholder; what's
important is the print data representation class.
For service formatted print data, the print data representation class is
typically one of the following (although other representation classes are
permitted). Nested classes inside class DocFlavor
declare predefined
static constant DocFlavor
objects for these example doc flavors;
class DocFlavor
's constructor can be used to create an arbitrary doc
flavor.
RenderableImage
. The
printer calls methods in that interface to obtain the image to be printed.
Printable
. The printer calls
methods in that interface to obtain the pages to be printed, one by one.
For each page, the printer supplies a graphics context, and whatever the
client draws in that graphics context gets printed.
Pageable
. The printer calls
methods in that interface to obtain the pages to be printed, one by one.
For each page, the printer supplies a graphics context, and whatever the
client draws in that graphics context gets printed.
("text/plain", "java.io.InputStream")
("text/plain; charset=us-ascii", "java.io.InputStream")
("text/plain; charset=utf-8", "java.io.InputStream")
("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")
Support for the above doc flavors is desirable so a printing client can rely on being able to print on any JPS printer, regardless of which doc flavors the printer supports. If the printer doesn't support the client's preferred doc flavor, the client can at least print plain text, or the client can convert its data to a renderable image and print the image.
Furthermore, every Java Print Service instance must fulfill these requirements for processing plain text print data:
DocFlavor
in package javax.print
is similar to class
java.awt.datatransfer.DataFlavor
. Class DataFlavor
is not
used in the Java Print Service (JPS) API for three reasons which are all
rooted in allowing the JPS API to be shared by other print services APIs
which may need to run on Java profiles which do not include all of the Java
Platform, Standard Edition.
java.awt.datatransfer.DataFlavor
does not guarantee that equivalent data flavors will have the same
serialized representation. DocFlavor
does, and can be used in
services which need this.
java.awt.datatransfer.DataFlavor
includes a human presentable name as part of the serialized representation.
This is not appropriate as part of a service matching constraint.
DocFlavor
's serialized representation uses the following
canonical form of a MIME type string. Thus, two doc flavors with MIME types
that are not identical but that are equivalent (that have the same canonical
form) may be considered equal.
DocFlavor
's serialized representation also contains the
fully-qualified class name of the representation class (a
String
object), rather than the representation class itself (a
Class
object). This allows a client to examine the doc flavors a Java
Print Service instance supports without having to load the representation
classes, which may be problematic for limited-resource clients.
Modifier and Type | Class and Description |
---|---|
public static class | DocFlavor.BYTE_ARRAY
Class |
public static class | DocFlavor.CHAR_ARRAY
Class |
public static class | DocFlavor.INPUT_STREAM
Class |
public static class | DocFlavor.READER
Class |
public static class | DocFlavor.SERVICE_FORMATTED
Class |
public static class | DocFlavor.STRING
Class |
public static class | DocFlavor.URL
Class |
Modifier and Type | Field and Description |
---|---|
public static final String | hostEncoding
A string representing the host operating system encoding. |
private String | myClassName
Representation class name. |
private transient MimeType | myMimeType
MIME type. |
private transient String | myStringValue
String value for this doc flavor. |
private static final long | serialVersionUID
Use serialVersionUID from JDK 1.4 for interoperability. |
Access | Constructor and Description |
---|---|
public |
Modifier and Type | Method and Description |
---|---|
public boolean | Returns: true if this doc flavor object equals obj ,
false otherwiseObject to testOverrides java. |
public String | Returns: the media sub-typeReturns this doc flavor object's media subtype (from the MIME type). |
public String | Returns: the media typeReturns this doc flavor object's media type (from the MIME type). |
public String | Returns: the mime typeReturns this doc flavor object's MIME type string based on the canonical form. |
public String | Returns: a string representing a mime parameter, ornull if that
parameter is not in the mime type stringthe name of the parameter. This name is internally
converted to the canonical lower case format before performing
the match. paramName)Returns a |
public String | Returns: the name of the representation classReturns the name of this doc flavor object's representation class. |
private String | |
public int | |
private void | readObject(ObjectInputStream
the input stream s)Reconstitute an instance from a stream (that is, deserialize it). |
public String | Returns: MIME type string based on the canonical form. Each parameter value is enclosed in quotes. A "class=" parameter is appended to the MIME type string to indicate the representation class name.Overrides java. DocFlavor to a string.
|
private void | writeObject(ObjectOutputStream
the output stream s)Write the instance to a stream (ie serialize the object). |