svn commit: rev 36619 - in avalon/trunk/central/site/src/xdocs/planet/facilities: . http reflector reflector/blocks reflector/components
[email protected] 19 Aug 2004 17:54:36 -0000
| Newsgroups | gmane.comp.jakarta.avalon.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: niclas
Date: Thu Aug 19 10:54:36 2004
New Revision: 36619
Added:
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/using.xml (contents, props changed)
Modified:
avalon/trunk/central/site/src/xdocs/planet/facilities/http/index.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/navigation.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/complete.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/index.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/navigation.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/standard.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/components/index.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/index.xml
avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/navigation.xml
Log:
More documentation for the reflector.
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/http/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/http/index.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/http/index.xml Thu Aug 19 10:54:36 2004
@@ -34,14 +34,13 @@
</subsection>
<subsection name="Component Requirement">
<p>
- The
- components that wishes to serve HTTP requests need to implement
- org.apache.avalon.http.HttpRequestHandler, which is a stripped
- down version of Jetty's org.mortbay.http.HttpHandler, taking the
- same arguments.
+ The components that wishes to serve HTTP requests need to
+ implement <code>org.apache.avalon.http.HttpRequestHandler</code>,
+ which is a stripped down version of Jetty's
+ org.mortbay.http.HttpHandler, taking the same arguments.
</p>
</subsection>
- <subsection name="Assmbled Facility">
+ <subsection name="Assembled Facility">
<p>
To make life easier for everyone involved, we have assembled a
couple of standard Jetty configurations, and these can easily be
@@ -63,5 +62,3 @@
</section>
</body>
</document>
-
-
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/navigation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/navigation.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/navigation.xml Thu Aug 19 10:54:36 2004
@@ -26,6 +26,7 @@
<item name="Finder" href="finder/index.html"/>
<item name="HTTP" href="http.html"/>
<item name="JMX" href="jmx.html"/>
+ <item name="Reflector" href="reflector/index.html"/>
</menu>
</body>
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/complete.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/complete.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/complete.xml Thu Aug 19 10:54:36 2004
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Avalon Planet - Facilities</title>
+ <title>Planet - Facilities</title>
<author email="[email protected]">Avalon Development Team</author>
</properties>
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/index.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/index.xml Thu Aug 19 10:54:36 2004
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Avalon Planet - Facilities</title>
+ <title>Planet - Facilities</title>
<author email="[email protected]">Avalon Development Team</author>
</properties>
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/navigation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/navigation.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/navigation.xml Thu Aug 19 10:54:36 2004
@@ -24,8 +24,8 @@
<body>
<menu>
<item name="Overview" href="index.html"/>
- <item name="standard" href="standard.html"/>
- <item name="complete" href="complete.html"/>
+ <item name="Standard" href="standard.html"/>
+ <item name="Complete" href="complete.html"/>
</menu>
</body>
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/standard.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/standard.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/blocks/standard.xml Thu Aug 19 10:54:36 2004
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Avalon Planet - Facilities</title>
+ <title>Planet - Facilities</title>
<author email="[email protected]">Avalon Development Team</author>
</properties>
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/components/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/components/index.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/components/index.xml Thu Aug 19 10:54:36 2004
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Avalon Planet - Facilities</title>
+ <title>Planet - Facilities</title>
<author email="[email protected]">Avalon Development Team</author>
</properties>
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/index.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/index.xml Thu Aug 19 10:54:36 2004
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Avalon Planet - Facilities</title>
+ <title>Planet - Facilities</title>
<author email="[email protected]">Avalon Development Team</author>
</properties>
Modified: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/navigation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/navigation.xml (original)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/navigation.xml Thu Aug 19 10:54:36 2004
@@ -26,7 +26,7 @@
<item name="Overview" href="index.html"/>
<item name="Using" href="using.html"/>
<item name="Components" href="components/index.html"/>
- <item name="Blocks" href="blocks.html"/>
+ <item name="Blocks" href="blocks/index.html"/>
</menu>
</body>
Added: avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/using.xml
==============================================================================
--- (empty file)
+++ avalon/trunk/central/site/src/xdocs/planet/facilities/reflector/using.xml Thu Aug 19 10:54:36 2004
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<!--
+ Copyright 2004 Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+
+ <properties>
+ <title>Planet - Facilities</title>
+ <author email="[email protected]">Avalon Development Team</author>
+ </properties>
+
+ <body>
+ <section name="Using the Reflector Facility">
+ <p>
+ The Reflector has two pre-defined blocks that can be used straight
+ up without any further configuration.
+ </p>
+ <p>
+ Example of including the Complete block in a larger block;
+ </p>
+<source>
+<![CDATA[
+<container name="myapplication" >
+ <classloader>
+ :
+ </classloader>
+
+ <component name="MyComponent" type="com.mycompany.myproject.MyComponent" />
+
+ <include
+ artifact="block:metro/facilities/reflector/metro-reflector-blocks-complete#SNAPSHOT" />
+
+</container>
+]]>
+</source>
+ <table>
+ <tr>
+ <th>Group</th>
+ <th>Name</th>
+ <th>Purpose</th>
+ </tr>
+ <tr>
+ <td>metro/facilities/reflector</td>
+ <td>metro-reflector-blocks-complete</td>
+ <td>
+ The Complete block consist of everything need when you don't have
+ the HTTP Facility available and used elsewhere in the system. It
+ starts the HTTP Facility on port 8080 with a normal socket listener
+ and registers the composition model as a root object in the
+ Reflector.
+ </td>
+ </tr>
+ <tr>
+ <td>metro/facilities/reflector</td>
+ <td>metro-reflector-blocks-standard</td>
+ <td>
+ The Standard block is intended for use when you want it to attach
+ itself to an existing HTTP Facility running on any port. By default,
+ the Reflector will lookup 'any' <code>HttpContext</code>, so it is
+ not defined which context it will add itself to. If you need better
+ control, you need to use the 'manual assembly' features of Merlin.
+ </td>
+ </tr>
+ </table>
+ <subsection name="Normal Use - My own Root objects." >
+ <p>
+ If you want to have your own root objects, you look up the Reflector
+ and call the <code>addRootObject( String name, Object object )</code>
+ method, either directly from your component, or preferably from a
+ separate component that does the registration.
+ </p>
+<source>
+/**
+ * @avalon.dependency type="org.apache.metro.facilities.reflector.ReflectorService"
+ * key="reflector"
+ * @avalon.dependency type="com.mycompany.myproject.MyApplication"
+ * key="app"
+ */
+public void service( ServiceManager man )
+ throws ServiceException
+{
+ MyApplication app = (MyApplication) man.lookup( "app" );
+ ReflectorService reflector = (ReflectorService) man.lookup( "reflector" );
+ reflector.addRootObject( app );
+}
+</source>
+ </subsection>
+ <subsection name="Normal Use - Direct utlization of Reflector" >
+ <p>
+ There are sometimes reasons to use the Reflector programmatically
+ and not using it as a troubleshooting tool only. For instance,
+ let's say that you define the entire application with events, and
+ that you want to enable that the user can subscribe to changes
+ via mail. You can then utilize the Reflector to provide for a
+ fairly understandable object model, i.e. the dot-notation, and
+ have a mail application register itself at each of the objects
+ defined in the mail. Another example of use is a report generator,
+ which has its fields defined with the dot-notation of the objects
+ that are the live data in the form.
+ </p>
+ <p>
+ The <code>ReflectorService</code> interface is fairly easy to
+ understand and has many convenience methods to make these sorts
+ of applications easier to write.
+ </p>
+ </subsection>
+ <subsection name="Advance Use - Defining my own TypeHandler" >
+ <p>
+ There might be reason to handle the containment of certain types
+ differently than the standard <code>ObjectTypeHandler</code>. Reasons
+ for this varies, but typically it would be that there are additional
+ information in the class or interface that you want to view or change.
+ You create a <code>TypeHandler</code> and implement each of the
+ methods.
+ </p>
+ <table>
+ <tr>
+ <th>Method signature</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>
+ boolean isDefault();
+ </td>
+ <td>
+ All implementations should return false, unless the purpose is
+ to provide a new default behaviour, instead of the
+ <code>ObjectTypeHandler</code>. This method is only called once
+ upon startup.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ String[] getNames( Object container )<br/>
+ throws ReflectionException;
+ </td>
+ <td>
+ This method should return an array of all the members of the
+ class. This determines which members are available in the type
+ the TypeHandler handles. This method is called for every object
+ introspected by the Reflector. The names returned will be used
+ as input in the methods below (i.e. the membername argument).
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Class getClass( Object container, String membername )<br/>
+ throws ReflectionException;
+ </td>
+ <td>
+ Return the Class of the member. The Class returned must be the
+ type of the reference, and not the Class of the object assigned to
+ the reference. In case of JavaBeans get methods, the Class returned
+ equals the return type of the get method. If the Class of the
+ object assigned to the reference is returned, then assignment
+ of new objects to the same reference will be required to be the
+ same class or a subclass of the Class returned from this method.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Object getMemberObject( Object container, String membername )<br/>
+ throws ReflectionException;
+ </td>
+ <td>
+ Return the object with the given membername.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ void setMemberObject( Object container, String membername, Object value )<br/>
+ throws ReflectionException;
+ </td>
+ <td>
+ Assignment of a new value to a member. For primitive types and
+ the subclasses of Number, the value (or true/false in case of
+ boolean) can either be the numeric object, or a string with
+ the value in it. For Number types a Double object will be
+ created and assigned. For all other types, you can pass a
+ String with the fully qualified class name, and a new object
+ of that class will be instantiated and assigned, provided that
+ the class can be found through the classloader hierarchy and
+ that it has a default (i.e. empty) constructor.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ boolean isSettable( Object container, String memberName )<br/>
+ throws ReflectionException;
+ </td>
+ <td>
+ This method should return <code>true</code> if it is possible
+ to modify the member, i.e. call the <code>setMemberObject</code>
+ method.
+ </td>
+ </tr>
+ </table>
+ </subsection>
+ </section>
+ </body>
+
+ <footer>
+ <legal>
+ Copyright (c) @year@ The Avalon Apache Project All rights reserved.
+ $Revision: 1.4 $ $Date: 2004/05/05 13:38:05 $
+ </legal>
+ </footer>
+</document>