Return-Path: Delivered-To: apmail-incubator-river-commits-archive@minotaur.apache.org Received: (qmail 88989 invoked from network); 24 Dec 2010 21:37:17 -0000 Received: from unknown (HELO mail.apache.org) (140.211.11.3) by 140.211.11.9 with SMTP; 24 Dec 2010 21:37:17 -0000 Received: (qmail 95789 invoked by uid 500); 24 Dec 2010 21:37:17 -0000 Delivered-To: apmail-incubator-river-commits-archive@incubator.apache.org Received: (qmail 95757 invoked by uid 500); 24 Dec 2010 21:37:17 -0000 Mailing-List: contact river-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: river-dev@incubator.apache.org Delivered-To: mailing list river-commits@incubator.apache.org Received: (qmail 95750 invoked by uid 99); 24 Dec 2010 21:37:17 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 24 Dec 2010 21:37:17 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 24 Dec 2010 21:37:10 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id E4AF723888FE; Fri, 24 Dec 2010 21:36:47 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r781552 - in /websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource: ./ Service.html ServiceConfigurationError.html package-frame.html package-summary.html package-tree.html package-use.html Date: Fri, 24 Dec 2010 21:36:47 -0000 To: river-commits@incubator.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20101224213647.E4AF723888FE@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: buildbot Date: Fri Dec 24 21:36:47 2010 New Revision: 781552 Log: Staging update by buildbot Added: websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/ websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/Service.html websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/ServiceConfigurationError.html websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-frame.html websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-summary.html websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-tree.html websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-use.html Added: websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/Service.html ============================================================================== --- websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/Service.html (added) +++ websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/Service.html Fri Dec 24 21:36:47 2010 @@ -0,0 +1,416 @@ + + + + + + +Service (Apache River v2.1.2-SNAPSHOT API Documentation) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+ +

+ +com.sun.jini.resource +
+Class Service

+
+java.lang.Object
+  extended by com.sun.jini.resource.Service
+
+
+
+
public final class Service
extends Object
+ + +

+A simple service-provider lookup mechanism. A service is a + well-known set of interfaces and (usually abstract) classes. A service + provider is a specific implementation of a service. The classes in a + provider typically implement the interfaces and subclass the classes defined + in the service itself. Service providers may be installed in an + implementation of the Java(TM) platform in the form of extensions, that is, + JAR files placed into any of the usual extension directories. Providers may + also be made available by adding them to the applet or application class + path or by some other platform-specific means. + +

In this lookup mechanism a service is represented by an interface or an + abstract class. (A concrete class may be used, but this is not + recommended.) A provider of a given service contains one or more concrete + classes that extend this service class with data and code specific to + the provider. This provider class will typically not be the entire + provider itself but rather a proxy that contains enough information to + decide whether the provider is able to satisfy a particular request together + with code that can create the actual provider on demand. The details of + provider classes tend to be highly service-specific; no single class or + interface could possibly unify them, so no such class has been defined. The + only requirement enforced here is that provider classes must have a + zero-argument constructor so that they may be instantiated during lookup. + +

A service provider identifies itself by placing a provider-configuration + file in the resource directory META-INF/services. The file's name + should consist of the fully-qualified name of the abstract service class. + The file should contain a list of fully-qualified concrete provider-class + names, one per line. Space and tab characters surrounding each name, as + well as blank lines, are ignored. The comment character is '#' + (0x23); on each line all characters following the first comment + character are ignored. The file must be encoded in UTF-8. + +

If a particular concrete provider class is named in more than one + configuration file, or is named in the same configuration file more than + once, then the duplicates will be ignored. The configuration file naming a + particular provider need not be in the same JAR file or other distribution + unit as the provider itself. The provider must be accessible from the same + class loader that was initially queried to locate the configuration file; + note that this is not necessarily the class loader that found the file. + +

Example: Suppose we have a service class named + java.io.spi.CharCodec. It has two abstract methods: + + 

+   public abstract CharEncoder getEncoder(String encodingName);
+   public abstract CharDecoder getDecoder(String encodingName);
+
+ + Each method returns an appropriate object or null if it cannot + translate the given encoding. Typical CharCodec providers will + support more than one encoding. + +

If sun.io.StandardCodec is a provider of the CharCodec + service then its JAR file would contain the file + META-INF/services/java.io.spi.CharCodec. This file would contain + the single line: + + 

+   sun.io.StandardCodec    # Standard codecs for the platform
+
+ + To locate an encoder for a given encoding name, the internal I/O code would + do something like this: + + 
+   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;
+   }
+
+ + The provider-lookup mechanism always executes in the security context of the + caller. Trusted system code should typically invoke the methods in this + class from within a privileged security context. +

+ +

+

+
Since:
+
2.0
+
Author:
+
Sun Microsystems, Inc.
+
+
+ +

+ + + + + + + + + + + + + + + + + + + + +
+Method Summary
+static IteratorinstalledProviders(Class service) + +
+          Locates and incrementally instantiates the available providers of a + given service using the extension class loader.
+static Iteratorproviders(Class service) + +
+          Locates and incrementally instantiates the available providers of a + given service using the context class loader.
+static Iteratorproviders(Class service, + ClassLoader loader) + +
+          Locates and incrementally instantiates the available providers of a + given service using the given class loader.
+  + + + + + + + +
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
+  +

+ + + + + + + + +
+Method Detail
+ +

+providers

+
+public static Iterator providers(Class service,
+                                 ClassLoader loader)
+                          throws ServiceConfigurationError
+
+
Locates and incrementally instantiates the available providers of a + given service using the given class loader. + +

This method transforms the name of the given service class into a + provider-configuration filename as described above and then uses the + getResources method of the given class loader to find all + available files with that name. These files are then read and parsed to + produce a list of provider-class names. The iterator that is returned + uses the given class loader to lookup and then instantiate each element + of the list. + +

Because it is possible for extensions to be installed into a running + virtual machine, this method may return different results each time + it is invoked.

+

+

+
Parameters:
service - The service's abstract service class
loader - The class loader to be used to load provider-configuration files + and instantiate provider classes, or null if the system + class loader (or, failing that the bootstrap class loader) is to + be used +
Returns:
An Iterator that yields provider objects for the given + service, in instantiation order. The iterator will throw a + ServiceConfigurationError if a provider-configuration + file violates the specified format or if a provider class cannot + be found and instantiated. +
Throws: +
ServiceConfigurationError - If a provider-configuration file violates the specified format + or names a provider class that cannot be found and instantiated
See Also:
providers(java.lang.Class), +installedProviders(java.lang.Class)
+
+
+
+ +

+providers

+
+public static Iterator providers(Class service)
+                          throws ServiceConfigurationError
+
+
Locates and incrementally instantiates the available providers of a + given service using the context class loader. This convenience method + is equivalent to + + 
+   ClassLoader cl = Thread.currentThread().getContextClassLoader();
+   return Service.providers(service, cl);
+
+

+

+
Parameters:
service - The service's abstract service class +
Returns:
An Iterator that yields provider objects for the given + service, in some arbitrary order. The iterator will throw a + ServiceConfigurationError if a provider-configuration + file violates the specified format or if a provider class cannot + be found and instantiated. +
Throws: +
ServiceConfigurationError - If a provider-configuration file violates the specified format + or names a provider class that cannot be found and instantiated
See Also:
providers(java.lang.Class, java.lang.ClassLoader)
+
+
+
+ +

+installedProviders

+
+public static Iterator installedProviders(Class service)
+                                   throws ServiceConfigurationError
+
+
Locates and incrementally instantiates the available providers of a + given service using the extension class loader. This convenience method + simply locates the extension class loader, call it + extClassLoader, and then does + + 
+   return Service.providers(service, extClassLoader);
+
+ + If the extension class loader cannot be found then the system class + loader is used; if there is no system class loader then the bootstrap + class loader is used. +

+

+
Parameters:
service - The service's abstract service class +
Returns:
An Iterator that yields provider objects for the given + service, in some arbitrary order. The iterator will throw a + ServiceConfigurationError if a provider-configuration + file violates the specified format or if a provider class cannot + be found and instantiated. +
Throws: +
ServiceConfigurationError - If a provider-configuration file violates the specified format + or names a provider class that cannot be found and instantiated
See Also:
providers(java.lang.Class, java.lang.ClassLoader)
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions. + + Added: websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/ServiceConfigurationError.html ============================================================================== --- websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/ServiceConfigurationError.html (added) +++ websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/ServiceConfigurationError.html Fri Dec 24 21:36:47 2010 @@ -0,0 +1,271 @@ + + + + + + +ServiceConfigurationError (Apache River v2.1.2-SNAPSHOT API Documentation) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+ +

+ +com.sun.jini.resource +
+Class ServiceConfigurationError

+
+java.lang.Object
+  extended by java.lang.Throwable
+      extended by java.lang.Error
+          extended by com.sun.jini.resource.ServiceConfigurationError
+
+
+
All Implemented Interfaces:
Serializable
+
+
+
+
public class ServiceConfigurationError
extends Error
+ + +

+Error thrown when something goes wrong while looking up service providers. + In particular, this error will be thrown in the following situations: + +

    +
  • A concrete provider class cannot be found, +
  • A concrete provider class cannot be instantiated, +
  • The format of a provider-configuration file is illegal, or +
  • An IOException occurs while reading a provider-configuration file. +
+

+ +

+

+
Since:
+
2.0
+
Author:
+
Sun Microsystems, Inc.
+
See Also:
Serialized Form
+
+ +

+ + + + + + + + + + + + + + +
+Constructor Summary
ServiceConfigurationError(String msg) + +
+          Constructs a new instance with the specified detail string.
ServiceConfigurationError(Throwable x) + +
+          Constructs a new instance that wraps the specified throwable.
+  + + + + + + + +
+Method Summary
+  + + + + + + + +
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
+  + + + + + + + +
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
+  +

+ + + + + + + + +
+Constructor Detail
+ +

+ServiceConfigurationError

+
+public ServiceConfigurationError(String msg)
+
+
Constructs a new instance with the specified detail string. +

+

+
+ +

+ServiceConfigurationError

+
+public ServiceConfigurationError(Throwable x)
+
+
Constructs a new instance that wraps the specified throwable. +

+

+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions. + + Added: websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-frame.html ============================================================================== --- websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-frame.html (added) +++ websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-frame.html Fri Dec 24 21:36:47 2010 @@ -0,0 +1,43 @@ + + + + + + +com.sun.jini.resource (Apache River v2.1.2-SNAPSHOT API Documentation) + + + + + + + + + + + +com.sun.jini.resource + + + + +
+Classes  + +
+Service
+ + + + + + +
+Errors  + +
+ServiceConfigurationError
+ + + + Added: websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-summary.html ============================================================================== --- websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-summary.html (added) +++ websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-summary.html Fri Dec 24 21:36:47 2010 @@ -0,0 +1,183 @@ + + + + + + +com.sun.jini.resource (Apache River v2.1.2-SNAPSHOT API Documentation) + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV PACKAGE  + NEXT PACKAGE + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+

+Package com.sun.jini.resource +

+Utility classes for manipulating resources. +

+See: +
+          Description +

+ + + + + + + + + +
+Class Summary
ServiceA simple service-provider lookup mechanism.
+  + +

+ + + + + + + + + +
+Error Summary
ServiceConfigurationErrorError thrown when something goes wrong while looking up service providers.
+  + +

+

+Package com.sun.jini.resource Description +

+ +

+Utility classes for manipulating resources. +

+ +

+

+
+
+ + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV PACKAGE  + NEXT PACKAGE + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions. + + Added: websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-tree.html ============================================================================== --- websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-tree.html (added) +++ websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-tree.html Fri Dec 24 21:36:47 2010 @@ -0,0 +1,154 @@ + + + + + + +com.sun.jini.resource Class Hierarchy (Apache River v2.1.2-SNAPSHOT API Documentation) + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package  Class  Use   Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+
+

+Hierarchy For Package com.sun.jini.resource +

+
+
+
Package Hierarchies:
All Packages
+
+

+Class Hierarchy +

+ +
+ + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package  Class  Use   Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions. + + Added: websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-use.html ============================================================================== --- websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-use.html (added) +++ websites/staging/river/trunk/content/river/doc/api/com/sun/jini/resource/package-use.html Fri Dec 24 21:36:47 2010 @@ -0,0 +1,166 @@ + + + + + + +Uses of Package com.sun.jini.resource (Apache River v2.1.2-SNAPSHOT API Documentation) + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package  Class   Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+
+

+Uses of Package
com.sun.jini.resource

+
+ + + + + + + + + +
+Packages that use com.sun.jini.resource
com.sun.jini.resourceUtility classes for manipulating resources. 
+  +

+ + + + + + + + +
+Classes in com.sun.jini.resource used by com.sun.jini.resource
ServiceConfigurationError + +
+          Error thrown when something goes wrong while looking up service providers.
+  +

+

+ + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package  Class   Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions. + +