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—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—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:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
