hammant 02/03/31 05:54:35
Modified: src/xdocs/framework book.xml index.xml
Added: src/xdocs/framework
separation-of-interface-and-implementation.xml
Log:
first draft of interface/impl document
Revision Changes Path
1.10 +1 -0 jakarta-avalon/src/xdocs/framework/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/framework/book.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- book.xml 31 Jan 2002 15:43:52 -0000 1.9
+++ book.xml 31 Mar 2002 13:54:35 -0000 1.10
@@ -21,6 +21,7 @@
<menu-item label="Reuse Standards" href="reuse-standards.html"/>
<menu-item label="Inversion of Control"
href="inversion-of-control.html"/>
<menu-item label="Separation of Concerns"
href="separation-of-concerns.html"/>
+ <menu-item label="Separation of Concerns"
href="separation-of-interface-and-implementation.html"/>
<menu-item label="Security" href="security.html"/>
</menu>
1.8 +12 -14 jakarta-avalon/src/xdocs/framework/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/framework/index.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- index.xml 31 Jan 2002 15:43:52 -0000 1.7
+++ index.xml 31 Mar 2002 13:54:35 -0000 1.8
@@ -19,25 +19,22 @@
best-of-practice pattern enforcements, and several
lightweight convenience implementations of the generic components.
</p>
- <p>
- What that means is that we define the central interface
<code>Component</code>.
- We also define the relationship (contract) a component has with
peers,
- ancestors and children. This documentation introduces you to those
patterns,
- interfaces and relationships.
- </p>
<s2 title="Target Audience">
<p>
- This documentation is aimed towards developers who are interested
- in the design principles of Avalon, or wish to develop code that
- will be incorporated into Avalon.
+ This documentation is aimed towards developers who:
+ <ul>
+ <li>are interested in the design principles of Avalon</li>
+ <li>wish to develop code that will be incorporated into
Avalon</li>
+ <li>wish to reuse Avalon concepts in their own application</li>
+ </ul>
</p>
</s2>
<s2 title="Theoretical Aspects of Component Development">
<p>
- The following documents provide basic theoretical concepts that
are applied
- through-out Avalon's framework. It would be good for a prospective
developer to
+ The following documents provide basic theoretical concepts that
are applied
+ through-out Avalon's framework. It would be good for a prospective
developer to
be at least passingly familiar with the concepts outlined in this
document.
- The documentation also provides links to outside sources which can
be consulted
+ The documentation also provides links to outside sources which can
be consulted
for further information.
</p>
<ol>
@@ -45,12 +42,13 @@
<li><link href="reuse-standards.html">Reuse Standards</link></li>
<li><link href="inversion-of-control.html">Inversion of
Control</link></li>
<li><link href="separation-of-concerns.html">Separation of
Concerns</link></li>
+ <li><link
href="separation-of-interface-and-implementation.html">Separation of Interface
and Implementation</link></li>
<li><link href="security.html">Security</link></li>
</ol>
</s2>
<s2 title="Concrete Descriptions of the Avalon Component model">
<p>
- This section describes concrete examples of how the theoretical
ideas
+ This section describes concrete examples of how the theoretical
ideas
are applied within the context of Avalon.
</p>
<ol>
@@ -65,7 +63,7 @@
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision: 1.7 $ $Date: 2002/01/31 15:43:52 $
+ $Revision: 1.8 $ $Date: 2002/03/31 13:54:35 $
</legal>
</footer>
</document>
1.1
jakarta-avalon/src/xdocs/framework/separation-of-interface-and-implementation.xml
Index: separation-of-interface-and-implementation.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Developer Documentation - Separation of Interface and
Implementation</title>
<authors>
<person name="Paul Hammant" email="[EMAIL PROTECTED]"/>
<person name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The core concept of interface and implementation separation is built
into
Java itself in that it has interfaces and classes. Many toolkits have
been developed along the lines of an API / implementation separation.
One such toolkit is the SAX API and the multiple XML parsers that
implement
it. Developers are quite happy using Apache's Xerces via the SAX API
and
understand that SAX represents the interface and Xerces an
implementation.
We notice that a lot of developers are happy to use interface/impl
separated tools, but not to make them. We will try to justify in this
document why we think people making applications should define
interface/impl boundaries early in the design cycle.
</p>
<s2 title="Justification">
<p>
The main reason we do it is because:
<ol>
<li>it forces you to decouple different
modules/components/objects</li>
<li>if specified correctly allows you to easily change the
implementation of
the interface/contract in the future</li>
<li>makes it possible for a user to read documentation about
interface
without having the implementation details clutter up their
perception</li>
<li>increases the possibility of reuse in a larger
application</li>
</ol>
</p>
<p>
If you are building objects with the aim of reuse then [2] is
important but
most people don't build for reuse (and most XP advocates say you
should just
plan to use not reuse) and thus [1] and [2] are more important. If
you feel
like documenting that and expanding this then feel free to.
</p>
</s2>
<s2 title="Example">
<p>
Let us hope this is not necessary:
</p>
<source>
package helloworld;
public interface HelloWorld {
void sayHello(String greeting);
}
package helloworld.impl.default;
public class DefaultHelloWorld implements HelloWorld {
void sayHello(String greeting) {
System.out.println("HelloWorld Greeting: " + greeting);
}
}
package helloworld.impl.remote;
public class RemoteHelloWorld implements HelloWorld {
private RemoteMessager mRemoteMessager;
public RemoteHelloWorld(RemoteMessager rm) {
RemoteMessager = rm;
}
void sayHello(String greeting) {
rm.sendMessage("HelloWorld Greeting: " + greeting);
}
}
</source>
</s2>
<s2 title="History">
<p>
We are referring to this pattern at <strong>interface/impl
separation</strong>.
Wiley's Patterns in Java book refers to it simply as 'Interface',
but we feel
that the word interface is overloaded enough in English and
computing.
</p>
<p>
It might be true to say that this is 'API/implementation
separation', but
this too could be confusing as the aforementioned SAX is not quite a
pure set of interfaces. It has a static factory that thunks in an
implementation that all subsequent calls to the factory method will
be
forced to use. See Anto-patterns below.
</p>
<p>
Better might be 'separation of implementation and the
interface/contract' as
that is quite correct, but a tad unwieldy.
</p>
</s2>
</s1>
<s1 title="Related topics">
<s2 title="Implementation hiding">
<p>
Once a tool is split into interface and impl, it is possible for a
container
to hide the implementation. Most containers already use dynamic
proxys
(Available in the JDK since 1.3), but we are talking about having
the classes
of the implementation hidden from classes using the interface.
</p>
<p>
To do this, it is easiest to mount the impl classes in a separate
classloader
to the classloader that the interface-using classes are mounted in.
The
interfaces being mounted in a classloader that is visible to both.
</p>
<p>
This is not a new proposition. Sun defined the servlet spec, and
included
rules about implementation hiding for hosted servlets. Essentially,
instantiated servlets are only allowed to 'see' classes from the
JDK, their
own WAR file and those of the Servlet API itself. Tomcat correctly
hides
the implementation of the Servlet API from the hosted servlets.
</p>
<p>
To actually achieve this separation, many containers (including
those from
the Avalon project) require that the interface and impl are in
separate jars.
Or to put it another way, there is no point separating your
interface and impl
classes if you are going to distribute them in the same jar.
</p>
</s2>
<s2 title="Kernel, Client API, Hosted Components">
<p>
This is building the previous section, and in short is referred to
as K/CAPI/HC.
Basically the Kernel mounts hosted components and satisfies their
need for a
client API. However the kernel wants to hide its implementation
from the hosted
components.
</p>
<p>
An EJB container is another good example of this. EntityBean,
SessionBean etc is
the client API. The hosted components are the beans, and the
container has a
kernel. It builds a complex tree of classloaders to separate its
implementation,
the client API, the JDK's runtime jar (that always being in the
system or
primordial classloader), and the hosted components.
</p>
<p>
The central message of this is that it you have interface/impl
separated your
tool, and are doing tricky things with more classloaders in the
implementation,
please make sure ytou do not assume that the parent classloader of
any classloader
is the system classoader. If your reusable tool has been taken by
another team
and at some non root place in a classloader tree, then the tools
will fail if
you have made such assumptions.
</p>
</s2>
<s2 title="Anti-patterns">
<p>
SAX, mentioned in multiple contexts in this document, is also an
example of
where the design can go wrong. The Factory is static (that in
itself is an
anti-pattern to IoC). Despite giving the appearance of having the
ability
to generate a parsr based on the impl's class name, only the first
caller
of that method will regsiter a parser for the whole environment to
use.
</p>
<p>
Given that the SAX API is now in the JDK, the environment we allude
to above
is the whole JVM. This is a problem because in a very complex
application
with differing concurrent needs for implementation of parsers, not
all can be
met if the SAX API is used for making parsers.
</p>
</s2>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/03/31 13:54:35 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
