index.html - turbine-fulcrum-factory - Git at Google

 <!DOCTYPE html>
 <!--
  | Generated by Apache Maven Doxia Site Renderer 1.9.2 from xdocs/index.xml at 21 September 2021
  | Rendered using Apache Maven Fluido Skin 1.9
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.2" />
     <meta name="author" content="Eric Pugh" />
     <meta name="author" content="Thomas Vandahl" />
     <title>Fulcrum Factory &#x2013; Factory Component</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.9.min.css" />
     <link rel="stylesheet" href="./css/site.css" />
     <link rel="stylesheet" href="./css/print.css" media="print" />
     <script src="./js/apache-maven-fluido-1.9.min.js"></script>
   </head>
   <body class="topBarDisabled">
     <div class="container-fluid">
       <header>
         <div id="banner">
           <div class="pull-left"><a href="https://turbine.apache.org/" id="bannerLeft" title="Apache Turbine"><img src="https://turbine.apache.org/images/turbine-project.png"  alt="Apache Turbine"/></a></div>
           <div class="pull-right"></div>
           <div class="clear"><hr/></div>
         </div>

         <div id="breadcrumbs">
           <ul class="breadcrumb">
         <li id="publishDate">Last Published: 21 September 2021<span class="divider">|</span>
 </li>
           <li id="projectVersion">Version: 1.1.2-SNAPSHOT</li>
       <li class="pull-right"><span class="divider">|</span>
 <a href="https://turbine.apache.org/fulcrum/" class="externalLink" title="Fulcrum">Fulcrum</a></li>
       <li class="pull-right"><span class="divider">|</span>
 <a href="https://turbine.apache.org/" class="externalLink" title="Turbine">Turbine</a></li>
       <li class="pull-right"><a href="https://www.apache.org" class="externalLink" title="Apache">Apache</a></li>
           </ul>
         </div>
       </header>
       <div class="row-fluid">
         <header id="leftColumn" class="span2">
           <nav class="well sidebar-nav">
   <ul class="nav nav-list">
    <li class="nav-header">Overview</li>
     <li class="active"><a href="#"><span class="none"></span>Main</a></li>
     <li><a href="tasks.html" title="ToDos"><span class="none"></span>ToDos</a></li>
    <li class="nav-header">Project Documentation</li>
     <li><a href="project-info.html" title="Project Information"><span class="icon-chevron-down"></span>Project Information</a>
      <ul class="nav nav-list">
       <li><a href="dependencies.html" title="Dependencies"><span class="none"></span>Dependencies</a></li>
       <li><a href="dependency-info.html" title="Dependency Information"><span class="none"></span>Dependency Information</a></li>
       <li><a href="distribution-management.html" title="Distribution Management"><span class="none"></span>Distribution Management</a></li>
       <li class="active"><a href="#"><span class="none"></span>About</a></li>
       <li><a href="issue-management.html" title="Issue Management"><span class="none"></span>Issue Management</a></li>
       <li><a href="licenses.html" title="Licenses"><span class="none"></span>Licenses</a></li>
       <li><a href="mailing-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li>
       <li><a href="plugin-management.html" title="Plugin Management"><span class="none"></span>Plugin Management</a></li>
       <li><a href="plugins.html" title="Plugins"><span class="none"></span>Plugins</a></li>
       <li><a href="scm.html" title="Source Code Management"><span class="none"></span>Source Code Management</a></li>
       <li><a href="summary.html" title="Summary"><span class="none"></span>Summary</a></li>
       <li><a href="team.html" title="Team"><span class="none"></span>Team</a></li>
      </ul></li>
     <li><a href="project-reports.html" title="Project Reports"><span class="icon-chevron-right"></span>Project Reports</a></li>
    <li class="nav-header">Apache</li>
     <li><a href="https://www.apache.org/" class="externalLink" title="Apache Website"><span class="none"></span>Apache Website</a></li>
     <li><a href="https://www.apache.org/licenses/" class="externalLink" title="License"><span class="none"></span>License</a></li>
     <li><a href="https://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works"><span class="none"></span>How the ASF works</a></li>
     <li><a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a></li>
     <li><a href="https://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a></li>
     <li><a href="https://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a></li>
   </ul>
           </nav>
           <div class="well sidebar-nav">
             <hr />
             <div id="poweredBy">
               <div class="clear"></div>
               <div class="clear"></div>
               <div class="clear"></div>
 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
             </div>
           </div>
         </header>
         <main id="bodyColumn"  class="span10" >


   <section>
 <h2><a name="Overview"></a>Overview</h2>

 <p>
 The Factory Service instantiates objects from the given class name
 using either the given class loader or an applicable one found from the class
 loader repository. If neither one is specified, the default class loader
 will be used.
 </p>


 <p>
 The service provides the following benefits compared to Class.forName():
 </p>

 <ul>

 <li>support for parameters in constructors,</li>

 <li>internal class loader repository, which can be specified in resources,</li>

 <li>optional class specific factories, which can be used for customized instantiation, and</li>

 <li>integration with the Pool Service supporting recycling of instances created by the service.</li>
 </ul>
   </section>

 <section>
 <h2><a name="Configuration"></a>Configuration</h2>
     <section>
 <h3><a name="Role_Configuration"></a>Role Configuration</h3>

 <div class="source"><pre class="prettyprint">
     &lt;role
         name=&quot;org.apache.fulcrum.factory.FactoryService&quot;
         shorthand=&quot;factory&quot;
         default-class=&quot;org.apache.fulcrum.factory.DefaultFactoryService&quot;/&gt;
       </pre></div>
     </section>

     <section>
 <h3><a name="Component_Configuration"></a>Component Configuration</h3>

 <table border="0" class="table table-striped">

 <tr class="a">

 <th>Item</th>

 <th>Datatype</th>

 <th>Cardinality</th>

 <th>Description</th>
         </tr>

 <tr class="b">

 <td>classloader</td>

 <td>String</td>

 <td>[0..n]</td>

 <td>
             A class loader. Class loaders will be tried in sequence when
             trying to create an object instance.
           </td>
         </tr>

 <tr class="a">

 <td>object-factory</td>

 <td>Complex</td>

 <td>[0|1]</td>

 <td>
             The parent element for object factories. Sub-elements define
             factories for certain class names. You can define one
             <code>default</code> factory that will be used if no others
             match. See the configuration example below.
           </td>
         </tr>
       </table>
     </section>

     <section>
 <h3><a name="Component_Configuration_Example"></a>Component Configuration Example</h3>

 <div class="source"><pre class="prettyprint">
     &lt;factory&gt;
         &lt;classloader&gt;java.net.URLClassLoader&lt;/classloader&gt;
         &lt;object-factory&gt;
             &lt;javax.xml.parsers.DocumentBuilder&gt;
                 org.foo.xml.DomBuilderFactory
             &lt;/javax.xml.parsers.DocumentBuilder&gt;
             &lt;default&gt;
                 org.some.default.Factory
             &lt;/default&gt;
         &lt;/object-factory&gt;
     &lt;/factory&gt;
       </pre></div>
     </section>
   </section>

   <section>
 <h2><a name="Usage"></a>Usage</h2>

 <p>
       In Turbine, the Factory Service is currently only used internally by the Pool Service.
       Applications can also use the service instead of Class.forName() and for unifying
       initialization, configuration and access to vendor specific object factories.
       The following is a simplified example of a customized DOM parser factory:
     </p>


 <div class="source"><pre class="prettyprint">
 package org.foo.xml;

 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
 import javax.xml.parsers.ParserConfigurationException;

 import org.apache.fulcrum.factroy.FactoryException;
 import org.apache.fulcrum.factory.Factory;

 /**
  * A factory for instantiating DOM parsers.
  */
 public class DomBuilderFactory implements Factory&lt;DocumentBuilder&gt;
 {
     /**
      * The implementation of the factory.
      */
     private DocumentBuilderFactory factory;

     /**
      * Initializes the factory.
      */
     public void init(String className)
         throws FactoryException
     {
         factory = DocumentBuilderFactory.newInstance();
     }

     /**
      * Gets a DocumentBuilder instance.
      */
     public DocumentBuilder getInstance()
         throws FactoryException
     {
         try
         {
             return factory.newDocumentBuilder();
         }
         catch (ParserConfigurationException x)
         {
             throw new FactoryException(x);
         }
     }

     /**
      * Gets a DocumentBuilder instance.
      * The given loader is ignored.
      */
     public DocumentBuilder getInstance(ClassLoader loader)
         throws FactoryException
     {
         return getInstance();
     }

     /**
      * Gets a DocumentBuilder instance.
      * Constructor parameters are ignored.
      */
     public DocumentBuilder getInstance(Object[] params, String[] signature)
         throws FactoryException
     {
         return getInstance();
     }

     /**
      * Gets a DocumentBuilder instance.
      * The given loader and constructor parameters are ignored.
      */
     public DocumentBuilder getInstance(ClassLoader loader,
         Object[] params,
         String[] signature)
         throws FactoryException
     {
         return getInstance();
     }

     /**
      * Returns false as given class loaders are not supported.
      */
     public boolean isLoaderSupported()
     {
         return false;
     }
 }
 </pre></div>


 <p>
       The customized DOM parser factory must be specified in the component
       configuration like in the configuration example above before it can
       be used.
     </p>


 <p>
     A DOM parser can now be instantiated with the following code fragment:
     </p>


 <div class="source"><pre class="prettyprint">
 // Access the service singleton.
 FactoryService service = (FactoryService)container.lookup(FactoryService.ROLE);

 // Create a new DOM parser.
 DocumentBuilder parser =
     service.getInstance(&quot;javax.xml.parsers.DocumentBuilder&quot;);
 </pre></div>

   </section>


         </main>
       </div>
     </div>
     <hr/>
     <footer>
       <div class="container-fluid">
         <div class="row-fluid">
             <p>&#169;      2005&#x2013;2021
 <a href="https://www.apache.org/">The Apache Software Foundation</a>
 </p>
         </div>
       </div>
     </footer>
   </body>
 </html>
	<!DOCTYPE html>
	<!--
	\| Generated by Apache Maven Doxia Site Renderer 1.9.2 from xdocs/index.xml at 21 September 2021
	\| Rendered using Apache Maven Fluido Skin 1.9
	-->
	<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
	<head>
	<meta charset="UTF-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.2" />
	<meta name="author" content="Eric Pugh" />
	<meta name="author" content="Thomas Vandahl" />
	<title>Fulcrum Factory – Factory Component</title>
	<link rel="stylesheet" href="./css/apache-maven-fluido-1.9.min.css" />
	<link rel="stylesheet" href="./css/site.css" />
	<link rel="stylesheet" href="./css/print.css" media="print" />
	<script src="./js/apache-maven-fluido-1.9.min.js"></script>
	</head>
	<body class="topBarDisabled">
	<div class="container-fluid">
	<header>
	<div id="banner">
	<div class="pull-left"><a href="https://turbine.apache.org/" id="bannerLeft" title="Apache Turbine"><img src="https://turbine.apache.org/images/turbine-project.png" alt="Apache Turbine"/></a></div>
	<div class="pull-right"></div>
	<div class="clear"><hr/></div>
	</div>

	<div id="breadcrumbs">
	<ul class="breadcrumb">
	<li id="publishDate">Last Published: 21 September 2021<span class="divider">\|</span>
	</li>
	<li id="projectVersion">Version: 1.1.2-SNAPSHOT</li>
	<li class="pull-right"><span class="divider">\|</span>
	<a href="https://turbine.apache.org/fulcrum/" class="externalLink" title="Fulcrum">Fulcrum</a></li>
	<li class="pull-right"><span class="divider">\|</span>
	<a href="https://turbine.apache.org/" class="externalLink" title="Turbine">Turbine</a></li>
	<li class="pull-right"><a href="https://www.apache.org" class="externalLink" title="Apache">Apache</a></li>
	</ul>
	</div>
	</header>
	<div class="row-fluid">
	<header id="leftColumn" class="span2">
	<nav class="well sidebar-nav">
	<ul class="nav nav-list">
	<li class="nav-header">Overview</li>
	<li class="active"><a href="#"><span class="none"></span>Main</a></li>
	<li><a href="tasks.html" title="ToDos"><span class="none"></span>ToDos</a></li>
	<li class="nav-header">Project Documentation</li>
	<li><a href="project-info.html" title="Project Information"><span class="icon-chevron-down"></span>Project Information</a>
	<ul class="nav nav-list">
	<li><a href="dependencies.html" title="Dependencies"><span class="none"></span>Dependencies</a></li>
	<li><a href="dependency-info.html" title="Dependency Information"><span class="none"></span>Dependency Information</a></li>
	<li><a href="distribution-management.html" title="Distribution Management"><span class="none"></span>Distribution Management</a></li>
	<li class="active"><a href="#"><span class="none"></span>About</a></li>
	<li><a href="issue-management.html" title="Issue Management"><span class="none"></span>Issue Management</a></li>
	<li><a href="licenses.html" title="Licenses"><span class="none"></span>Licenses</a></li>
	<li><a href="mailing-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li>
	<li><a href="plugin-management.html" title="Plugin Management"><span class="none"></span>Plugin Management</a></li>
	<li><a href="plugins.html" title="Plugins"><span class="none"></span>Plugins</a></li>
	<li><a href="scm.html" title="Source Code Management"><span class="none"></span>Source Code Management</a></li>
	<li><a href="summary.html" title="Summary"><span class="none"></span>Summary</a></li>
	<li><a href="team.html" title="Team"><span class="none"></span>Team</a></li>
	</ul></li>
	<li><a href="project-reports.html" title="Project Reports"><span class="icon-chevron-right"></span>Project Reports</a></li>
	<li class="nav-header">Apache</li>
	<li><a href="https://www.apache.org/" class="externalLink" title="Apache Website"><span class="none"></span>Apache Website</a></li>
	<li><a href="https://www.apache.org/licenses/" class="externalLink" title="License"><span class="none"></span>License</a></li>
	<li><a href="https://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works"><span class="none"></span>How the ASF works</a></li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a></li>
	<li><a href="https://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a></li>
	<li><a href="https://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a></li>
	</ul>
	</nav>
	<div class="well sidebar-nav">
	<hr />
	<div id="poweredBy">
	<div class="clear"></div>
	<div class="clear"></div>
	<div class="clear"></div>
	<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
	</div>
	</div>
	</header>
	<main id="bodyColumn" class="span10" >




	<section>
	<h2><a name="Overview"></a>Overview</h2>

	<p>
	The Factory Service instantiates objects from the given class name
	using either the given class loader or an applicable one found from the class
	loader repository. If neither one is specified, the default class loader
	will be used.
	</p>


	<p>
	The service provides the following benefits compared to Class.forName():
	</p>

	<ul>

	<li>support for parameters in constructors,</li>

	<li>internal class loader repository, which can be specified in resources,</li>

	<li>optional class specific factories, which can be used for customized instantiation, and</li>

	<li>integration with the Pool Service supporting recycling of instances created by the service.</li>
	</ul>
	</section>

	<section>
	<h2><a name="Configuration"></a>Configuration</h2>
	<section>
	<h3><a name="Role_Configuration"></a>Role Configuration</h3>

	<div class="source"><pre class="prettyprint">
	<role
	name="org.apache.fulcrum.factory.FactoryService"
	shorthand="factory"
	default-class="org.apache.fulcrum.factory.DefaultFactoryService"/>
	</pre></div>
	</section>

	<section>
	<h3><a name="Component_Configuration"></a>Component Configuration</h3>

	<table border="0" class="table table-striped">

	<tr class="a">

	<th>Item</th>

	<th>Datatype</th>

	<th>Cardinality</th>

	<th>Description</th>
	</tr>

	<tr class="b">

	<td>classloader</td>

	<td>String</td>

	<td>[0..n]</td>

	<td>
	A class loader. Class loaders will be tried in sequence when
	trying to create an object instance.
	</td>
	</tr>

	<tr class="a">

	<td>object-factory</td>

	<td>Complex</td>

	<td>[0\|1]</td>

	<td>
	The parent element for object factories. Sub-elements define
	factories for certain class names. You can define one
	<code>default</code> factory that will be used if no others
	match. See the configuration example below.
	</td>
	</tr>
	</table>
	</section>

	<section>
	<h3><a name="Component_Configuration_Example"></a>Component Configuration Example</h3>

	<div class="source"><pre class="prettyprint">
	<factory>
	<classloader>java.net.URLClassLoader</classloader>
	<object-factory>
	<javax.xml.parsers.DocumentBuilder>
	org.foo.xml.DomBuilderFactory
	</javax.xml.parsers.DocumentBuilder>
	<default>
	org.some.default.Factory
	</default>
	</object-factory>
	</factory>
	</pre></div>
	</section>
	</section>

	<section>
	<h2><a name="Usage"></a>Usage</h2>

	<p>
	In Turbine, the Factory Service is currently only used internally by the Pool Service.
	Applications can also use the service instead of Class.forName() and for unifying
	initialization, configuration and access to vendor specific object factories.
	The following is a simplified example of a customized DOM parser factory:
	</p>


	<div class="source"><pre class="prettyprint">
	package org.foo.xml;

	import javax.xml.parsers.DocumentBuilder;
	import javax.xml.parsers.DocumentBuilderFactory;
	import javax.xml.parsers.ParserConfigurationException;

	import org.apache.fulcrum.factroy.FactoryException;
	import org.apache.fulcrum.factory.Factory;

	/**
	* A factory for instantiating DOM parsers.
	*/
	public class DomBuilderFactory implements Factory<DocumentBuilder>
	{
	/**
	* The implementation of the factory.
	*/
	private DocumentBuilderFactory factory;

	/**
	* Initializes the factory.
	*/
	public void init(String className)
	throws FactoryException
	{
	factory = DocumentBuilderFactory.newInstance();
	}

	/**
	* Gets a DocumentBuilder instance.
	*/
	public DocumentBuilder getInstance()
	throws FactoryException
	{
	try
	{
	return factory.newDocumentBuilder();
	}
	catch (ParserConfigurationException x)
	{
	throw new FactoryException(x);
	}
	}

	/**
	* Gets a DocumentBuilder instance.
	* The given loader is ignored.
	*/
	public DocumentBuilder getInstance(ClassLoader loader)
	throws FactoryException
	{
	return getInstance();
	}

	/**
	* Gets a DocumentBuilder instance.
	* Constructor parameters are ignored.
	*/
	public DocumentBuilder getInstance(Object[] params, String[] signature)
	throws FactoryException
	{
	return getInstance();
	}

	/**
	* Gets a DocumentBuilder instance.
	* The given loader and constructor parameters are ignored.
	*/
	public DocumentBuilder getInstance(ClassLoader loader,
	Object[] params,
	String[] signature)
	throws FactoryException
	{
	return getInstance();
	}

	/**
	* Returns false as given class loaders are not supported.
	*/
	public boolean isLoaderSupported()
	{
	return false;
	}
	}
	</pre></div>


	<p>
	The customized DOM parser factory must be specified in the component
	configuration like in the configuration example above before it can
	be used.
	</p>


	<p>
	A DOM parser can now be instantiated with the following code fragment:
	</p>


	<div class="source"><pre class="prettyprint">
	// Access the service singleton.
	FactoryService service = (FactoryService)container.lookup(FactoryService.ROLE);

	// Create a new DOM parser.
	DocumentBuilder parser =
	service.getInstance("javax.xml.parsers.DocumentBuilder");
	</pre></div>

	</section>


	</main>
	</div>
	</div>
	<hr/>
	<footer>
	<div class="container-fluid">
	<div class="row-fluid">
	<p>© 2005–2021
	<a href="https://www.apache.org/">The Apache Software Foundation</a>
	</p>
	</div>
	</div>
	</footer>
	</body>
	</html>