crafterm 2002/10/23 09:08:20
Added: xfc/src/xdocs how.xml index.xml issues.xml menu.xml todo.xml
using.xml whatis.xml
Log:
Import of draft XFC documentation
Revision Changes Path
1.1 jakarta-avalon-excalibur/xfc/src/xdocs/how.xml
Index: how.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>How does XFC work ?</title>
<authors>
<person name="Marcus Crafter" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Basic concepts">
<p>
XFC works via input & output modules. Input & output modules define
the format style XFC should read and write to. Currently, modules for
ExcaliburComponentManager and Fortress exist.
</p>
<p>
When invoked, the names of the input & output modules are specified,
including a context which defines settings for each module. XFC
then processes the files defined by each context, creating configuration
files for the target format.
</p>
<p>
The name of the input & output module to be used is actually the
name
of the class that implements the
<code>org.apache.excalibur.xfc.Module</code>
interface. Aliases do exist for current Avalon containers however:
</p>
<ol>
<li>ExcaliburComponenetManager</li>
<p>
Module classname:
<code>org.apache.excalibur.xfc.modules.ecm.ECM</code>,
alias: <code>ecm</code>.
</p>
<li>Fortress</li>
<p>
Module classname:
<code>org.apache.excalibur.xfc.modules.fortress.Fortress</code>,
alias: <code>fortress</code>.
</p>
</ol>
</s1>
<s1 title="Modules">
<p>
Input & output modules adhere to the
<code>org.apache.excalibur.xfc.Module</code>
interface, which defines operations for creating and serializing a
<code>org.apache.excalibur.xfc.model.Model object</code>.
</p>
<p>
Module implementations can populate a Model instance with the definitions
of component roles, and instances defined. They can also take a
precreated Model and convert it to their specific container configuration
format.
</p>
<p>
The Model object and it's consituents are defined in the
<code>org.apache.excalibur.xfc.model</code> package.
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/10/23 16:08:20 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-excalibur/xfc/src/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>About Excalibur XFC</title>
<authors>
<person name="Marcus Crafter" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
This is the Excalibur <strong>X</strong>Conf <strong>F</strong>ile
<strong>C</strong>onverter package which contains a tool for
converting between container configuration files.
</p>
<p>
Using XFC it's possible to convert your older ECM configuration
files into a format understood, for example, by Fortress.
</p>
<p>
XFC consists of several packages that define a generic model for
component definitions and an input/output module interface for
supporting conversions between specific containers.
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/10/23 16:08:20 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-excalibur/xfc/src/xdocs/issues.xml
Index: issues.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Issues</title>
<authors>
<person name="Marcus Crafter" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Known problems">
<ol>
<li>Custom component selectors (ECM)</li>
<p>
ComponentSelectors are not portable amongst containers since are they
are essentially subcontainers, and tied to a particular container
implementation.
</p>
<p>
Due to this non portability problems, custom ComponentSelectors are
ignored,
and standard selectors are used whenever a ComponentSelector
definition is
being defined (eg. ExcaliburComponentSelector, when converting to
ECM).
</p>
<li>ID Attributes (Fortress)</li>
<p>
Fortress xconf files usually contain an id for each component
instantiation,
which are used as hints when selecting between different
implementations
of the same role.
</p>
<p>
The Fortress module creates the id attributes from the shorthand name
of the component, or the hint name of the component if it exists. In
the case where someone has defined a single implementation component
without
using a role manager neither of these values exist, so the string
UNKNOWN
is inserted as the ID.
</p>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/10/23 16:08:20 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-excalibur/xfc/src/xdocs/menu.xml
Index: menu.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<project href="http://jakarta.apache.org/avalon/excalibur/xfc/"; name="Excalibur XFC">
<title>Excalibur XFC</title>
<body>
<menu name="About">
<item href="index.html" name="About XFC"/>
<item href="http://jakarta.apache.org/avalon/excalibur/index.html";
name="Excalibur Home"/>
<item href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";
name="Download"/>
<item href="api/" name="API Docs"/>
</menu>
<menu name="Overview">
<item href="whatis.html" name="What is XFC ?"/>
<item href="how.html" name="How does XFC work ?"/>
<item href="using.html" name="How do I use XFC ?"/>
<item href="issues.html" name="Known issues"/>
<item href="todo.html" name="Todo"/>
</menu>
<!--
<menu name="How To">
<item href="ecm-howto.html" name="Convert to/from ECM"/>
<item href="fortress-howto.html" name="Convert to/from Fortress"/>
</menu>
-->
</body>
</project>
1.1 jakarta-avalon-excalibur/xfc/src/xdocs/todo.xml
Index: todo.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>What's left ?</title>
<authors>
<person name="Marcus Crafter" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Current XFC TODO list">
<ol>
<li>Lots of testing :)</li>
<li>Merlin module</li>
<li>Migration of logging categories</li>
<li>Invetigation into using the meta subproject as the underlying Model
XFC uses to store component data in, rather than the custom one
built in org.apache.excalibur.xfc.model.</li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/10/23 16:08:20 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-excalibur/xfc/src/xdocs/using.xml
Index: using.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using XFC ?</title>
<authors>
<person name="Marcus Crafter" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Calling XFC from the command line">
<p>
The XFC distribution includes a script called runconverter.sh/bat which can
be used to invoke XFC from the command line. It accepts two parameters
naming
the input and output modules, eg:
</p>
<source>
<![CDATA[
runconverter.sh --input ecm:ecm.roles:ecm.xconf --output fortress:f.roles:f.xconf
]]>
</source>
<p>
All supported options can be listed by supplying <code>--help</code> as
a parameter:
<source>
<![CDATA[
$> ./runconverter --help
XFC - The Avalon Excalibur (X)Conf (F)ile (C)onverter
Usage: java org.apache.excalibur.xfc.Main [options]
Options:
-h, --help
print this message and exit
-v, --version
print this version and exit
-i, --input <argument>
set the input module name and context
-o, --output <argument>
set the output module name and context
-d, --debug
enable debug logging
Example:
java org.apache.excalibur.xfc.Main\
--input ecm:conf/ecm.roles:conf/ecm.xconf \
--output fortress:conf/fortress.roles:conf/fortress.xconf
]]>
</source>
</p>
</s1>
<s1 title="Calling XFC from an ANT task">
<p>
The XFC distribution includes an ANT task (defined in the
<code>org.apache.excalibur.xfc.ant.XFCTask</code> class).
</p>
<p>
To use the ANT task, include the following custom task definition
in your build.xml:
</p>
<source>
<![CDATA[
<!-- Test XFC Ant task -->
<taskdef name="xfc" classname="org.apache.excalibur.xfc.ant.XFCTask">
<classpath refid="your.projects.class.path"/>
</taskdef>
]]>
</source>
<p>
and then call XFC as a normal ANT task defining your input and output
module types and contexts:
</p>
<source>
<![CDATA[
<xfc>
<input module="ecm" context="ecm.roles:ecm.xconf"/>
<output module="fortress" context="fortress.roles:fortress.xconf"/>
</xfc>
]]>
</source>
</s1>
<s1 title="Calling XFC from Java">
<p>
It's also possible to invoke XFC from within Java. To do this call the
method <code>org.apache.excalibur.xfc.Main.main</code>, and pass as an
array of String objects the same parameters you would normally give on
the command line.
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/10/23 16:08:20 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-excalibur/xfc/src/xdocs/whatis.xml
Index: whatis.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>What is XFC ?</title>
<authors>
<person name="Marcus Crafter" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The Avalon project consists of several different containers that
developers can use to write Components based on the Avalon Framework.
</p>
<p>
Each Avalon container however, is configured by a different set of
configuration files, that are incompatible with other containers.
</p>
<p>
ExcaliburComponentManager for example, uses an xconf/roles concept
to specify components, whereas Merlin uses an xinfo/xprofile
concept. Fortress uses a variation of ExcaliburComponentManager
configuration files, whereas Tweety uses a flat properties file.
</p>
<p>
The goal of XFC is to provide a tool that is able to port
configuration files from one container's format to another. This will
hopefully automate and ease migration between containers.
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/10/23 16:08:20 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <mailto:avalon-cvs-unsubscribe@;jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@;jakarta.apache.org>
