commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bay...@apache.org
Subject cvs commit: jakarta-commons/discovery/xdocs adc-guidelines.xml best-practices.xml
Date Wed, 18 Feb 2004 10:14:01 GMT
bayard      2004/02/18 02:14:01

  Added:       discovery/xdocs adc-guidelines.xml best-practices.xml
  Log:
  documentation moved from html to xml, by use of script
  
  Revision  Changes    Path
  1.1                  jakarta-commons/discovery/xdocs/adc-guidelines.xml
  
  Index: adc-guidelines.xml
  ===================================================================
  <document>
  <properties>
  <title>Architecture/Design/Coding Guidelines for Jakarta Commons &quot;Discovery&quot;
Component</title>
  </properties>
  <body>
  
  
  
  <section name="Architecture/Design/Coding Guidelines for Jakarta Commons &quot;Discovery&quot;
Component">
  $Id: adc-guidelines.xml,v 1.1 2004/02/18 10:14:01 bayard Exp $<br/>
  <a href="#Introduction">[Introduction]</a>
  <a href="#Security and doPrivileged()">[Security and doPrivileged()]</a>
  <br/><br/>
  
  
  
  <a name="Introduction"></a>
  
  <subsection name="1.  Introduction">
  
  Kick-off: set of design/architectural guidelines.
  This should serve as both a record of decisions made,
  and a list of open issues.
  
  
  <a name="Security and doPrivileged()"></a>
  </subsection>
  <subsection name="2.  Security and doPrivileged()">
  Do not use doPrivileged() instructions within discovery.
  That remains the responsibility of the end-user.
  
  </subsection>
  </section>
  </body>
  </document>
  
  
  
  1.1                  jakarta-commons/discovery/xdocs/best-practices.xml
  
  Index: best-practices.xml
  ===================================================================
  <document>
  <properties>
  <title>Best Practices for using Jakarta Commons &quot;Discovery&quot; Component</title>
  </properties>
  <body>
  
  
  
  <section name="Best Practices for using Jakarta Commons &quot;Discovery&quot;
Component">
  $Id: best-practices.xml,v 1.1 2004/02/18 10:14:01 bayard Exp $<br />
  <a href="#Introduction">[Introduction]</a>
  <a href="#Discovery Services">[Discovery Services]</a>
  <a href="#Additional Tools">[Additional Tools]</a>
    <a href="#Calling Directly">[Calling Directly]</a>
    <a href="#Integrating into Factories : Wrapping">[Integrating into Factories : Wrapping]</a>
  <br /><br />
  
  
  
  <a name="Introduction"></a>
  
  <subsection name="1.  INTRODUCTION">
  
  Best-practices are discussed.
  See the javadoc, starting with <code>DiscoverySingleton</code> and <code>DiscoverClass</code>,
  for detail on the API:
  where service implementations are looked for,
  the order in which those places are checked,
  which classloaders are used,
  and the order in which they are used.
  
  
  <a name="Discovery Services"></a>
  </subsection>
  <subsection name="2.  DISCOVERY SERVICES">
  <a name="Additional Tools"></a>
  </subsection>
  <subsection name="3.  ADDITIONAL TOOLS">
  
  <a name="Calling Directly"></a>
  <h4>3.1.  CALLING DIRECTLY</h4>
  
  <a name="Finding Singleton Instances (Factories)"></a>
  <h5>3.1.1.  Finding Singleton Instances (Factories)</h5>
  
  <p>DiscoverSingleton finds, loads, and manages the lifecycle of a class implementing
  a given interface.  It only supports classes with default (zero-argument) constructors.
  DiscoverSingleton can pass a set of properties to the class
  (see <a href="#Service Life Cycle Management">[Service Life Cycle Management]</a>).
  Use of the term singleton should be applied loosely:
  DiscoverSingleton will instantiate separate instances of a class if called with
  different:
  <ul>
    <li>thread context class loaders
        (for example, within different web applications in a J2EE managed environment)</li>
    <li>group contexts
        (maintain separation between different subsystems, if desired)</li>
  </ul>
  </p>
  
  <p>To call discovery directly from user-code:
  <ul>
  <pre>
      import org.apache.commons.discovery.DiscoverSingleton;
      import org.apache.commons.logging.LogFactory;
      ...
      LogFactory logFactory = (LogFactory)DiscoverSingleton.find(LogFactory.class);
  </pre>
  </ul>
  DiscoverSingleton looks for the value of the system property
  <code>org.apache.commons.logging.LogFactory</code>
  for the name of a class that implements the <code>LogFactory</code> (abstract)
class.
  Failing that, it uses JDK1.3-style service discovery.
  </p>
  <p>
  DiscoverSingleton also allows a <code>java.util.Properties</code>
  parameter to be used for query for service implementation class name,
  as well as a default implementation class name:
  <ul>
  <pre>
      LogFactory factory =
          (LogFactory)DiscoverSingleton.find(LogFactory.class,
                                             properties,
                                             LogFactory.FACTORY_DEFAULT);
  </pre>
  </ul>
  </p>
  <p>
  The properties can also be specified as a resource name:
  <ul>
  <pre>
      LogFactory factory =
          (LogFactory)DiscoverSingleton.find(LogFactory.class,
                                             LogFactory.FACTORY_PROPERTIES,
                                             LogFactory.FACTORY_DEFAULT);
  </pre>
  </ul>
  This last form is equivalent in function
  to the original <code>LogFactory.getFactory()</code>
  method.
  </p>
  <p>
  There are a variety of <code>find</code> methods
  provided by <code>DiscoverSingleton</code>, review the javadoc for
  other forms and options available.
  </p>
  
  <a name="Finding Classes"></a>
  <h5>3.1.2.  Finding Classes</h5>
  
  <p>DiscoverClass finds and loads a class implementing a given interface.
  DiscoverClass can pass a set of properties to the class if it implements
  the <code>Service</code> interface (which doesn't support full-lifecycle
  management as does the <code>SingletonService</code> interface).
  </p>
  
  <p>
  DiscoverClass provides API's that instantiate a class, though it currently
  supports only classes with default (zero-argument) constructors.
  Unlike <code>DiscoverySingleton</code>, class instances are not cached,
  so each call will result in a new object instance.
  </p>
  
  <p>
  DiscoverClass is more oriented toward calling multiple times within similar contexts,
  so it's use is slightly different than DiscoverSingleton: where as DiscoverSingleton provides
  a set of static methods (no state), DiscoverClass must be instantiated before it is
  used and maintains internal state.
  </p>
  
  <p>To find a class directly from user-code:
  [NEED BETTER EXAMPLE]
  <ul>
  <pre>
      import org.apache.commons.discovery.DiscoverClass;
      import org.apache.commons.logging.LogFactory;
      ...
      DiscoverClass discoverClass = new DiscoverClass();
      Class logFactoryClass = (LogFactory)discoverClass.find(LogFactory.class);
  </pre>
  </ul>
  In this case, DiscoverClass looks for the value of the system property
  <code>org.apache.commons.logging.LogFactory</code>
  for the name of a class that implements the <code>LogFactory</code> (abstract)
class.
  Failing that, it uses JDK1.3-style service discovery.
  </p>
  
  <p>To instantiate a class directly from user-code:
  [NEED BETTER EXAMPLE]
  <ul>
  <pre>
      import org.apache.commons.discovery.DiscoverClass;
      import org.apache.commons.logging.LogFactory;
      ...
      DiscoverClass discoverClass = new DiscoverClass();
      LogFactory logFactoryClass = (LogFactory)discoverClass.newInstance(LogFactory.class);
  </pre>
  </ul>
  </p>
  <p>
  As with DiscoverSingleton, DiscoverClass provides methods that
  use <code>java.util.Properties</code> and a default implementation class name
  to help determine the name of the class.
  </p>
  
  <a name="Integrating into Factories : Wrapping"></a>
  <h4>3.2  INTEGRATING INTO FACTORIES : WRAPPING</h4>
  
  
  <p>In this example, a factory (such as is used in commons-logging)
  internalizes the discovery mechanism, passing appropriate defaults
  for a default properties file and a default implementation.
  In this case, the factory plays double duty as both the service
  to be discovered (abstract class), and the discovery mechanism.
  
  <ul>
  <pre>
  import java.util.Properties;
  import org.apache.commons.discovery.DiscoverSingleton;
  import org.apache.commons.discovery.DiscoveryException;
  
  public abstract class LogFactory
  {
      protected static final String FACTORY_DEFAULT =
          org.apache.commons.logging.impl.DefaultLogFactory.class.getName();
  
      protected static final String FACTORY_PROPERTIES =
          "commons-logging.properties";
  
      /**
       * Protected constructor that is not available for public use.
       */
      protected LogFactory() { }
  
      public static LogFactory getFactory() throws ServiceException
      {
          return (LogFactory)DiscoverSingleton.find(LogFactory.class,
                                                    LogFactory.class,
                                                    FACTORY_PROPERTIES,
                                                    FACTORY_DEFAULT);
      }
  
      public static LogFactory getFactory(Properties properties)
          throws ServiceException
      {
          return (LogFactory)DiscoverSingleton.find(LogFactory.class,
                                                    LogFactory.class,
                                                    properties,
                                                    FACTORY_DEFAULT);
      }
      ...
  }
  </pre>
  </ul>
  Note the addition of one extra parameter to the <code>find</code>
  method call.
  The first parameter is a <i>root wrapper class</i>,
  which delegates to the discovery mechanism.
  This is necessary to all <code>Discovery</code>
  to determine the correct class loaders to be used
  in loading an implementation class.
  The second parameter is the service interface/class
  for which <code>Discovery</code> will be looking for an implementation.
  In this example, they are the same class, as the LogFactory
  is providing helper methods that 'wrap' <code>Discovery</code>.
  </p>
   
  </subsection>
  </section>
  </body>
  </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message