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".)
A 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
Unicde characters in the array.
String --
The print data consists of the Unicode characters in the string.
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.
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.
For byte print data where the doc flavor's MIME type does not include a
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 gurantee that two VM's 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.hostEncoding
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.
The Java Print Service API does not define any mandatorily supported 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 |
In general, preformatted text print data is provided either in a character oriented representation class (character array, String, Reader) or in a byte oriented representation class (byte array, InputStream, URL).
| MIME-Type | Description |
|---|---|
"application/pdf" |
Portable Document Format document |
"application/postscript" |
PostScript document |
"application/vnd.hp-PCL" |
Printer Control Language document |
In general, preformatted PDL print data is provided in a byte oriented representation class (byte array, InputStream, URL).
| MIME-Type | Description |
|---|---|
"image/gif" |
Graphics Interchange Format image |
"image/jpeg" |
Joint Photographic Experts Group image |
"image/png" |
Portable Network Graphics image |
In general, preformatted image print data is provided in a byte oriented representation class (byte array, InputStream, URL).
| MIME-Type | Description |
|---|---|
"application/octet-stream" |
The print data format is unspecified (just an octet stream) |
The printer decides how to interpret the print data; the way this "autosensing" works is implementation dependent. In general, preformatted autosense print data is provided in a byte oriented representation class (byte array, InputStream, URL).
For service formatted print data, the Java Print Service instance
determines the print data format. The doc flavor's representation class
denotes an interface whose methods the DocPrintJob invokes to
determine the content to be printed -- such as a renderable image
interface or a Java 2 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.
("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")
A Java Print Service instance is allowed to support any other doc flavors (or none) in addition to the above mandatory ones, at the implementation's choice.
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:
The client must itself perform all plain text print data formatting not addressed by the above requirements.
Class DocFlavor in package javax.print.data is similar to class
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 2 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.
Class 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.
Class 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.
DocFlavor, has a MIME type equivalent to this doc
flavor object's MIME type (that is, the MIME types have the same media
type, media subtype, and parameters), and has the same representation
class name as this doc flavor object. Thus, if two doc flavor objects'
MIME types are the same except for comments, they are considered equal.
However, two doc flavor objects with MIME types of "text/plain" and
"text/plain; charset=US-ASCII" are not considered equal, even though
they represent the same media type (because the default character
set for plain text is US-ASCII).String representing a MIME
parameter.
Mime types may include parameters which are usually optional.
The charset for text types is a commonly useful example.
This convenience method will return the value of the specified
parameter if one was specified in the mime type for this flavor.
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
DocFlavor to a string.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.