avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject cvs commit: jakarta-avalon/src/documentation/xdocs/developing framework.xml implementing.xml
Date Tue, 30 Oct 2001 16:16:43 GMT
bloritsch    01/10/30 08:16:43

  Modified:    src/documentation/xdocs/developing framework.xml
                        implementing.xml
  Log:
  Arrange the best practices with Does first and Don'ts last.  Also applied more fixes from
Marcus Crafter
  
  Revision  Changes    Path
  1.4       +30 -16    jakarta-avalon/src/documentation/xdocs/developing/framework.xml
  
  Index: framework.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/documentation/xdocs/developing/framework.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- framework.xml	2001/10/30 13:59:34	1.3
  +++ framework.xml	2001/10/30 16:16:43	1.4
  @@ -42,7 +42,8 @@
   <![CDATA[
   package org.apache.bizserver.docs;
   
  -public interface DocumentRepository {
  +public interface DocumentRepository extends Component
  +{
       String ROLE = "org.apache.bizserver.docs.DocumentRepository";
   
       Document getDocument(Principal requestor, int refId);
  @@ -54,33 +55,46 @@
           <itemizedlist>
             <listitem>
               <para>
  -              Only specify the methods you need.  The client should have no
  -              knowledge of implementation details, and too many alternative
  -              methods only introduce unneeded complexity.  In other words pick
  -              an approach and stick with it.
  +              Include a String called "ROLE" that has the role's official name.
  +              That name is the same as the fully qualified name for the work
  +              interface.  This helps later on when we need to get an instance
  +              of the Component later.
               </para>
             </listitem>
             <listitem>
               <para>
  -              Don't let your Role's interface extend any other interface.  If you
  -              think that you should extend another interface, it should be another
  -              Role's interface.  The only exception to this rule is when the Role's
  -              interface is a specialization of another Role.
  +              Do extend the Component interface if possible.  This makes it easier
  +              on you when it is time to release your Component.  If you are not
  +              in control of the work interface, then you do not have this option.
  +              It is not the end of the world, as you can recast the instance to
  +              <classname>Component</classname> when it is time to release it.
               </para>
             </listitem>
             <listitem>
               <para>
  -              Don't extend interfaces that impact implementation&mdash;you are
  -              mixing concerns and this will only lead to debugging and
  -              implementation problems later.
  +              Do one thing and do it well.  A Component should have the simplest
  +              interface possible, When your work interface extends several other
  +              interfaces, you muddy the contract for this Component.  An old
  +              American acronym helps define this pattern: Keep It Simple, Stupid
  +              (KISS).  It's not hard to outsmart yourself&mdash;I've done it
  +              a number of times myself.
               </para>
             </listitem>
             <listitem>
               <para>
  -              Include a String called "ROLE" that has the role's official name.
  -              That name is the same as the fully qualified name for the work
  -              interface.  This helps later on when we need to get an instance
  -              of the Component later.
  +              Only specify the methods you need.  The client should have no
  +              knowledge of implementation details, and too many alternative
  +              methods only introduce unneeded complexity.  In other words pick
  +              an approach and stick with it.
  +            </para>
  +          </listitem>
  +          <listitem>
  +            <para>
  +              Don't let your Role's interface extend any lifecycle or lifestyle
  +              interfaces.  By implementing any of those classes of interfaces, you
  +              are tying an implementation to the specification.  This is a
  +              bad pattern and this will only lead to debugging and implementation
  +              problems later.
               </para>
             </listitem>
           </itemizedlist>
  
  
  
  1.7       +4 -4      jakarta-avalon/src/documentation/xdocs/developing/implementing.xml
  
  Index: implementing.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/documentation/xdocs/developing/implementing.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- implementing.xml	2001/10/30 14:25:22	1.6
  +++ implementing.xml	2001/10/30 16:16:43	1.7
  @@ -397,9 +397,9 @@
           <para>
             The ComponentHandler interface is very simple to deal with.  You
             initialize the Constructor with the Java class, the Configuration
  -          object, the ConfigurationManager, a Context object, and a
  -          RoleManager.  If you know that your Component will not need any of
  -          the aforementioned items, you can pass a null in its place.  After
  +          object, the ComponentManager, a Context object, and a RoleManager.
  +          If you know that your Component will not need any of the
  +          aforementioned items, you can pass a null in its place.  After
             that, when you need a reference to the Component, you call the "get"
             method.  After you are done with it, you call the "put" method and
             pass the Component back to the ComponentHandler.  The following code
  @@ -646,7 +646,7 @@
               this.getClass().getClassLoader()
               .getResourceAsStream("/org/apache/bizserver/docs/document.roles"));
   
  -RoleManager roles = new DefaultRoleManager();
  +DefaultRoleManager roles = new DefaultRoleManager();
   roles.setLogger(Hierarchy.getDefaultHierarchy().getLoggerFor("document.roles"));
   roles.configure(roleConfig);
   
  
  
  

--
To unsubscribe, e-mail:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message