//******************************************************************************
//
// File:    StringDoc.java
// Package: org.jpwg.jini.print.data
// Unit:    Class org.jpwg.jini.print.data.StringDoc
//
//******************************************************************************

package org.jpwg.jini.print.data;

import java.io.IOException;
import java.io.Reader;
import java.io.StringReader;

import javax.print.attribute.DocAttributeSet;

import javax.print.DocFlavor;

/**
 * Class StringDoc is an implementation of interface {@link 
 * net.jini.print.data.Doc Doc} that provides a string as a piece of print data 
 * in a doc flavor with MIME type = <CODE>"text/plain; charset=unicode"</CODE> 
 * and representation class name = <CODE>"java.lang.String"</CODE>. The {@link 
 * AbstractDoc#getPrintData() <CODE>getPrintData()</CODE>} method returns a 
 * String, and the return value can be cast from class Object to class String. 
 * <P>
 * Class StringDoc stores the string to be printed in an internal field. If a 
 * StringDoc object is passed as an argument or return value of a remote method 
 * invocation (RMI), the entire string is serialized and sent to the remote 
 * location inside the StringDoc object. The recipient must have enough storage 
 * available to hold the entire string. Thus, class StringDoc is not recommended 
 * for transferring a large quantity of print data; use a character stream (e.g. 
 * class {@link ReaderDoc ReaderDoc}), byte stream (e.g. class {@link 
 * InputStreamDoc InputStreamDoc}), or URL (e.g. class {@link URLDoc URLDoc}) 
 * instead. 
 * <P>
 * <B>DRAFT STANDARD VERSION 1.0 (23-MAY-2000)</B>
 *
 * @author  Alan Kaminsky
 * @version 18-May-2000
 */
public class StringDoc
	extends AbstractDoc
	{

// Exported constructors.

	/**
	 * Construct a string doc object.
	 *
	 * @param  theData        String to be printed.
	 * @param  theAttributes  Unmodifiable set of printing attributes, or null
	 *                        to request the Print Job's default values. 
	 *
	 * @exception  NullPointerException
	 *     (unchecked exception) Thrown if <CODE>theData</CODE> is null. 
	 */
	public StringDoc
		(String theData,
		 DocAttributeSet theAttributes)
		{
		super (DocFlavor.STRING.TEXT_PLAIN, verify (theData), theAttributes);
		}

	private static String verify
		(String theData)
		{
		if (theData == null)
			{
			throw new NullPointerException
				("org.jpwg.jini.print.data.StringDoc.StringDoc(): theData is null");
			}
		return theData;
		}

// Exported operations inherited and overridden from class AbstractDoc.

	/**
	 * Obtain a reader for extracting character print data from this doc. This 
	 * doc's print data representation object (string) is obtained, then a 
	 * reader for reading the print data from the print data representation 
	 * object as a stream of characters is created and returned. 
	 *
	 * @return  Reader for reading the print data characters from this doc.
	 *
	 * @exception  IOException
	 *     Thrown if there was an I/O error while creating the reader.
	 */
	public Reader getReaderForText()
		throws IOException
		{
		return new StringReader ((String) getPrintData());
		}

	}