//******************************************************************************
//
// File:    LocalizedPrintService.java
// Package: net.jini.print.service
// Unit:    Interface net.jini.print.service.LocalizedPrintService
//
//******************************************************************************

package net.jini.print.service;

import java.rmi.RemoteException;

import java.util.Locale;

import javax.print.attribute.Attribute;

import javax.print.DocFlavor;

/**
 * Interface LocalizedPrintService specifies the capability for determining 
 * localized versions of print data formats, printing attribute categories, and 
 * printing attribute values. Interface LocalizedPrintService represents an 
 * optional capability that a Jini Print Service instance need not provide. If 
 * this capability is provided, the Jini Print Service proxy object will 
 * implement interface LocalizedPrintService. 
 * <P>
 * Each of the <CODE>localize()</CODE> methods uses the following algorithm to 
 * determine the locale to use, given the locale the caller specified and the 
 * locales the printer supports. (This is similar to the algorithm class {@link 
 * java.util.ResourceBundle java.util.ResourceBundle} uses.) 
 * <OL TYPE=1>
 * <LI>
 * If the caller specified the locale
 * <CODE>"<I>Language_Country_Variant</I>"</CODE>: 
 * <OL TYPE=a>
 * <LI>
 * If the printer supports the locale 
 * <CODE>"<I>Language_Country_Variant</I>"</CODE>, then the printer uses that 
 * locale. 
 * <LI>
 * Else if the printer supports the locale 
 * <CODE>"<I>Language_Country</I>"</CODE>, then the printer uses that locale. 
 * <LI>
 * Else if the printer supports the locale <CODE>"<I>Language</I>"</CODE>, then 
 * the printer uses that locale. 
 * <LI>
 * Else the printer uses the printer's default locale.
 * </OL>
 * <LI>
 * Else if the caller specified the locale 
 * <CODE>"<I>Language_Country</I>"</CODE>: 
 * <OL TYPE=a>
 * <LI>
 * If the printer supports the locale <CODE>"<I>Language_Country</I>"</CODE>, 
 * then the printer uses that locale. 
 * <LI>
 * Else if the printer supports the locale <CODE>"<I>Language</I>"</CODE>, then 
 * the printer uses that locale. 
 * <LI>
 * Else the printer uses the printer's default locale.
 * </OL>
 * <LI>
 * Else if the caller specified the locale <CODE>"<I>Language</I>"</CODE>: 
 * <OL TYPE=a>
 * <LI>
 * If the printer supports the locale <CODE>"<I>Language</I>"</CODE>, then the 
 * printer uses that locale. 
 * <LI>
 * Else the printer uses the printer's default locale.
 * </OL>
 * <LI>
 * Else (the caller specified a null locale or a locale other than one of the 
 * above forms) the printer uses the printer's default locale. 
 * </OL>
 * <P>
 * If the printer supports the locale 
 * <CODE>"<I>Language_Country_Variant</I>"</CODE>, then the printer must also 
 * support the locale <CODE>"<I>Language_Country</I>"</CODE>. If the printer 
 * supports the locale <CODE>"<I>Language_Country</I>"</CODE>, then the printer 
 * must also support the locale <CODE>"<I>Language</I>"</CODE>. The printer must 
 * always support some default locale. Interface LocalizedPrintService provides 
 * <B>capability methods</B> that let the client discover the specific locales 
 * for which the printer can provide localized strings as well as the default 
 * locale. In addition, for each locale it supports the printer includes a 
 * service attribute of class {@link net.jini.print.lookup.LocaleEntry 
 * LocaleEntry} in its service registration in the Jini Lookup Service (JLUS). 
 * <P>
 * There is no restriction on the number of client threads that may be 
 * simultaneously accessing the same Print Service. Therefore, all 
 * implementations of interface {@link PrintService PrintService} and its 
 * subinterfaces must be designed to be multiple thread safe. 
 * <P>
 * Interface LocalizedPrintService's methods all throw {@link 
 * java.rmi.RemoteException RemoteException} to provide for the possibility that 
 * the Print Service object's implementation performs remote method calls. The 
 * Print Service object's implementation in fact may or may not perform remote 
 * method calls. 
 * <P>
 * <B>DRAFT STANDARD VERSION 1.0 (23-MAY-2000)</B>
 *
 * @author  Alan Kaminsky
 * @version 12-May-2000
 */
public interface LocalizedPrintService
	extends PrintService
	{

// Exported operations.

	/**
	 * Returns a localized string for the given print data format in the given 
	 * locale. A print data format is designated by a "doc flavor" (class {@link 
	 * javax.print.data.DocFlavor DocFlavor}) consisting of a MIME type plus 
	 * a print data representation class. The returned string is a localized 
	 * version of just the MIME type. 
	 * <P>
	 * If this Print Service does not support the given locale, it will instead 
	 * use a supported locale that best matches the given locale as described 
	 * above. 
	 *
	 * @param  theFlavor  Doc flavor to localize.
	 * @param  theLocale  Locale to use, or null to use this Print Service's
	 *                    default locale. 
	 *
	 * @return  Localized string for <CODE>theFlavor</CODE> in
	 *          <CODE>theLocale</CODE>.
	 *
	 * @exception  NullPointerException
	 *     (unchecked exception) Thrown if <CODE>theFlavor</CODE> is null.
	 * @exception  RemoteException
	 *     Thrown if a remote error occurred.
	 */
	public String localize
		(DocFlavor theFlavor,
		 Locale theLocale)
		throws RemoteException;

	/**
	 * Returns a localized string for the given printing attribute category in 
	 * the given locale. A printing attribute category is designated by a {@link 
	 * java.lang.Class Class} that implements interface {@link 
	 * javax.print.attribute.Attribute Attribute}. 
	 * <P>
	 * If this Print Service does not support the given locale, it will instead 
	 * use a supported locale that best matches the given locale as described 
	 * above. 
	 *
	 * @param  theCategory  Printing attribute category to localize. It must be
	 *                      a {@link java.lang.Class Class} that implements 
	 *                      interface {@link javax.print.attribute.Attribute 
	 *                      Attribute}. 
	 * @param  theLocale    Locale to use, or null to use this Print Service's
	 *                      default locale. 
	 *
	 * @return  Localized string for <CODE>theCategory</CODE> in
	 *          <CODE>theLocale</CODE>.
	 *
	 * @exception  NullPointerException
	 *     (unchecked exception) Thrown if <CODE>theCategory</CODE> is null.
	 * @exception  IllegalArgumentException
	 *     (unchecked exception) Thrown if <CODE>theCategory</CODE> is not a 
	 *     {@link java.lang.Class Class} that implements interface {@link 
	 *     javax.print.attribute.Attribute Attribute}. 
	 * @exception  RemoteException
	 *     Thrown if a remote error occurred.
	 */
	public String localize
		(Class theCategory,
		 Locale theLocale)
		throws RemoteException;

	/**
	 * Returns a localized string for the given printing attribute value in the 
	 * given locale. A printing attribute value is an instance of a class that 
	 * implements interface {@link javax.print.attribute.Attribute Attribute}. 
	 * <P>
	 * If this Print Service does not support the given locale, it will instead 
	 * use a supported locale that best matches the given locale as described 
	 * above. 
	 * <P>
	 * If <CODE>theValue</CODE> is an instance of the {@link 
	 * javax.print.attribute.TextSyntax TextSyntax} abstract syntax class, then 
	 * <CODE>theValue</CODE> already is a localized string in some locale. In 
	 * this case the <CODE>localize()</CODE> method just returns the attribute's 
	 * text string; the <CODE>localize()</CODE> method does not try to translate 
	 * the text string from the text string's own language to 
	 * <CODE>theLocale</CODE>'s language. 
	 *
	 * @param  theValue   Printing attribute value to localize.
	 * @param  theLocale  Locale to use, or null to use this Print Service's
	 *                    default locale. 
	 *
	 * @return  Localized string for <CODE>theValue</CODE> in
	 *          <CODE>theLocale</CODE>.
	 *
	 * @exception  NullPointerException
	 *     (unchecked exception) Thrown if <CODE>theValue</CODE> is null.
	 * @exception  RemoteException
	 *     Thrown if a remote error occurred.
	 */
	public String localize
		(Attribute theValue,
		 Locale theLocale)
		throws RemoteException;

	/**
	 * Determine the locales this Print Service supports.
	 *
	 * @return  Array of the supported locales.
	 *
	 * @exception  RemoteException
	 *     Thrown if a remote error occurred.
	 */
	public Locale[] getSupportedLocales()
		throws RemoteException;

	/**
	 * Determine whether this Print Service supports the given locale.
	 *
	 * @param  theLocale  Locale to test.
	 *
	 * @return  True if this Print Service supports <CODE>theLocale</CODE>,
	 *          false if it doesn't.
	 *
	 * @exception  NullPointerException
	 *     (unchecked exception) Thrown if <CODE>theLocale</CODE> is null.
	 * @exception  RemoteException
	 *     Thrown if a remote error occurred.
	 */
	public boolean isLocaleSupported
		(Locale theLocale)
		throws RemoteException;

	/**
	 * Determine this Print Service's default locale.
	 *
	 * @return  Default locale.
	 *
	 * @exception  RemoteException
	 *     Thrown if a remote error occurred.
	 */
	public Locale getDefaultLocale()
		throws RemoteException;

	}