Name: rmT116609			Date: 03/16/2004


A DESCRIPTION OF THE REQUEST :
The documentation for the JAR file format includes discussion of "Service Providers"

http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider

The example given references a class 'Service':

However 'Service' is not part of the regular supported JDK, its a class in sun.misc.
Thus the public documentation for the JAR file format Service Provider mechanism recommends using an unsupported class that most developers will not be able to find!

sun.misc.Service needs to become a supported class, probably under java.util.jar or some other suitable java.* location.


JUSTIFICATION :
Multiple implementations and users of this class have sprung up. Its used by Java Media APIs, by JINI, by Xerces and by Batik. There should be a standard implementation built in to the JDK.

Service Providers have been a documented feature of the JAR file format since JDK 1.3, but the Service class is missing.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Documented class should be available.
ACTUAL -
Class is in sun.misc. Is unsupported.

---------- BEGIN SOURCE ----------

//the class Service is not documented anywhere, because it is in sun.misc!

CharEncoder getEncoder(String encodingName) {
       Iterator ps = Service.providers(CharCodec.class);
       while (ps.hasNext()) {
           CharCodec cc = (CharCodec)ps.next();
           CharEncoder ce = cc.getEncoder(encodingName);
           if (ce != null)
               return ce;
       }
       return null;
   }
---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
The only workarounds are for each developer to implement the same functionality for themselves, or to use an unsupported sun.misc class.
(Incident Review ID: 243662) 
======================================================================