incubator-aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mahrw...@apache.org
Subject svn commit: r928179 - in /incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint: NamespaceHandler.java ParserContext.java Processor.java
Date Sat, 27 Mar 2010 10:02:17 GMT
Author: mahrwald
Date: Sat Mar 27 10:02:17 2010
New Revision: 928179

URL: http://svn.apache.org/viewvc?rev=928179&view=rev
Log:
ARIES-249 More javadoc: NamespaceHandler and ParserContext

Modified:
    incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/NamespaceHandler.java
    incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/ParserContext.java
    incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/Processor.java

Modified: incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/NamespaceHandler.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/NamespaceHandler.java?rev=928179&r1=928178&r2=928179&view=diff
==============================================================================
--- incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/NamespaceHandler.java
(original)
+++ incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/NamespaceHandler.java
Sat Mar 27 10:02:17 2010
@@ -53,10 +53,20 @@ import org.osgi.service.blueprint.reflec
  * <li>A namespace handler should not return new metadata instances from the <code>decorate</code>
method if 
  * the same result could also be achieved by operating on a <code>MutableComponentMetadata</code>
instance.
  * </li>
+ * <li>A namespace handler should not assume the existence of predefined entries in
the component definition
+ * registry such as <code>blueprintBundle</code> or <code>blueprintBundleContext</code>.
In the case of a dry
+ * parse (i.e. a parse of the blueprint xml files without a backing OSGi bundle), these values
will not be 
+ * available
+ * </li>
  * </ul>
  */
 public interface NamespaceHandler  {
-    
+    /**
+     * Retrieve a URL from where the schema for a given namespace can be retrieved
+     * @param namespace The schema's namespace
+     * @return A URL that points to the location of the schema or null if the namespace validation
+     * is not needed
+     */
     URL getSchemaLocation(String namespace);
 
     /**
@@ -71,6 +81,18 @@ public interface NamespaceHandler  {
      */
     Set<Class> getManagedClasses();
     
+    /**
+     * Parse a stand-alone blueprint component 
+     *
+     * Given an <code>Element</code> node as a root, this method parses the stand-alone
component and returns its
+     * metadata. The supplied <code>ParserContext</code> should be used to parse
embedded blueprint elements as well
+     * as creating metadata.
+     * 
+     * @param element The DOM element representing the custom component
+     * @param context The <code>ParserContext</code> for parsing sub-components
and creating metadata objects
+     * @return A metadata instance representing the custom component. This should be an instance
of an appropriate
+     * <code>MutableMetadata</code> type to enable further decoration by other
namespace handlers
+     */
     Metadata parse(Element element, ParserContext context);
     
     /**

Modified: incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/ParserContext.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/ParserContext.java?rev=928179&r1=928178&r2=928179&view=diff
==============================================================================
--- incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/ParserContext.java
(original)
+++ incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/ParserContext.java
Sat Mar 27 10:02:17 2010
@@ -22,15 +22,48 @@ import org.w3c.dom.Element;
 import org.w3c.dom.Node;
 
 public interface ParserContext  {
-    
+    /**
+     * Returns the DOM Node that was passed to the NamespaceHandler call for which
+     * this ParserContext instance was created.
+     */
     Node getSourceNode();
 
     ComponentDefinitionRegistry getComponentDefinitionRegistry();
     
+    /**
+     * Retrieve the <code>ComponentMetadata</code> of the component that
+     * encloses the current <code>Node</code> that is to be parsed by a 
+     * namespace handler.
+     * 
+     * In case of top-level components this method will return <code>null</code>.
+     * @returns the enclosing component's metadata or null if there is no enclosing component
+     */
     ComponentMetadata getEnclosingComponent();
     
+    /**
+     * Create a new metadata instance of the given type. The returned
+     * object will also implement the appropriate <code>MutableComponentMetadata</code>
+     * interface, so as to allow the caller to set the properties of the 
+     * metadata.
+     *
+     * Note that the returned object may not be initialised, so callers
+     * should take care to assure every property needed by the blueprint
+     * extender is set.
+     *
+     * @param type the class of the Metadata object to create
+     * @param <T> The expected Metadata type to be created
+     * @return a new instance
+     */
     <T extends Metadata> T createMetadata(Class<T> type);
 
+    /**
+     * Invoke the blueprint parser to parse a DOM element.
+     * @param type the class of the Metadata type to be parsed
+     * @param enclosingComponent The component metadata that contains the Element
+     * to be parsed
+     * @param element The DOM element that is to be parsed
+     * @param <T> The expected metadata type to be parsed
+     */
     <T> T parseElement(Class<T> type, ComponentMetadata enclosingComponent, Element
element);
 
     /** 
@@ -39,10 +72,19 @@ public interface ParserContext  {
      */
     String generateId();
     
+    /**
+     * Get the default activation setting for the current blueprint file
+     */
     String getDefaultActivation();
     
+    /**
+     * Get the default availability setting for the current blueprint file
+     */
     String getDefaultAvailability();
     
+    /**
+     * Get the default timeout setting for the current blueprint file
+     */
     String getDefaultTimeout();
 }
 

Modified: incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/Processor.java
URL: http://svn.apache.org/viewvc/incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/Processor.java?rev=928179&r1=928178&r2=928179&view=diff
==============================================================================
--- incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/Processor.java
(original)
+++ incubator/aries/trunk/blueprint/blueprint-core/src/main/java/org/apache/aries/blueprint/Processor.java
Sat Mar 27 10:02:17 2010
@@ -19,7 +19,7 @@
 package org.apache.aries.blueprint;
 
 /**
+ * Marker interface for blueprint processors such as <code>BeanProcessor</code>
or
+ * <code>ServiceProcessor</code>
  */
-public interface Processor {
-
-}
+public interface Processor {}



Mime
View raw message