You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hivemind.apache.org by ah...@apache.org on 2007/02/06 22:11:03 UTC
svn commit: r504292 - in
/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations:
./ internal/
Author: ahuegen
Date: Tue Feb 6 13:11:02 2007
New Revision: 504292
URL: http://svn.apache.org/viewvc?view=rev&rev=504292
Log:
Improved javadoc
Modified:
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AbstractAnnotatedModule.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedModuleReader.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedRegistryBuilder.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotationsMessages.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Configuration.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Contribution.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Module.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Registry.java
hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/internal/RegistryImpl.java
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AbstractAnnotatedModule.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AbstractAnnotatedModule.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AbstractAnnotatedModule.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AbstractAnnotatedModule.java Tue Feb 6 13:11:02 2007
@@ -2,6 +2,12 @@
import org.apache.hivemind.service.Autowiring;
+/**
+ * Ancestor for annotated module classes. Provides convenience methods
+ * for the access to {@link Registry} and {@link Autowiring}.
+ *
+ * @author Achim Huegen
+ */
public class AbstractAnnotatedModule
{
private Registry _registry;
@@ -16,11 +22,19 @@
_registry = registry;
}
+ /**
+ * @return a reference to the {@link Autowiring} service.
+ */
public Autowiring getAutowiring()
{
return _registry.getAutowiring();
}
+ /**
+ * Autowires any object by use of the {@link Autowiring} service.
+ * @param target the object to wire
+ * @return the wired object
+ */
public <T> T autowireProperties(T target)
{
return (T) getAutowiring().autowireProperties(target);
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedModuleReader.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedModuleReader.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedModuleReader.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedModuleReader.java Tue Feb 6 13:11:02 2007
@@ -31,11 +31,20 @@
private ClassResolver _classResolver;
+ /**
+ * @param registryDefinition the registry definition to which the modules are added.
+ */
public AnnotatedModuleReader(RegistryDefinition registryDefinition)
{
this(registryDefinition, new DefaultClassResolver(), new DefaultErrorHandler());
}
+ /**
+ * @param registryDefinition the registry definition to which the modules are added.
+ * @param classResolver the {@link ClassResolver} used to resolve all classes referenced from
+ * elements inside this module.
+ * @param errorHandler errorHandler used for handling recoverable errors
+ */
public AnnotatedModuleReader(RegistryDefinition registryDefinition, ClassResolver classResolver,
ErrorHandler errorHandler)
{
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedRegistryBuilder.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedRegistryBuilder.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedRegistryBuilder.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotatedRegistryBuilder.java Tue Feb 6 13:11:02 2007
@@ -23,27 +23,46 @@
private ErrorHandler _errorHandler;
private Locale _locale;
+ /**
+ * Constructor that uses default implementations of ClassResolver, ErrorHandler and Locale.
+ */
public AnnotatedRegistryBuilder()
{
this(new DefaultClassResolver(), new DefaultErrorHandler(), Locale.getDefault());
}
+ /**
+ * Creates a new instance.
+ * @param classResolver the {@link ClassResolver} used to resolve all classes referenced from
+ * elements inside this module.
+ * @param errorHandler errorHandler used for handling recoverable errors
+ * @param locale the locale to use for the registry
+ */
public AnnotatedRegistryBuilder(ClassResolver classResolver, ErrorHandler errorHandler,
Locale locale)
{
_classResolver = classResolver;
_errorHandler = errorHandler;
_locale = locale;
-
}
+ /**
+ * Constructs a registry from a couple of annotated module classes specified by their name.
+ * @param moduleClassNames the annotated module class names
+ * @return the registry
+ */
public Registry constructRegistry(String ... moduleClassNames)
{
RegistryDefinition definition = constructRegistryDefinition(moduleClassNames);
return RegistryBuilder.constructRegistry(definition, _errorHandler, _locale);
}
- public Registry constructRegistry(Class ... moduleClasses)
+ /**
+ * Constructs a registry from a couple of annotated module classes specified by their class definitions.
+ * @param moduleClasses the annotated module classes
+ * @return the registry
+ */
+ public Registry constructRegistry(Class ... moduleClasses)
{
RegistryDefinition definition = constructRegistryDefinition(moduleClasses);
return RegistryBuilder.constructRegistry(definition, _errorHandler, _locale);
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotationsMessages.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotationsMessages.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotationsMessages.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/AnnotationsMessages.java Tue Feb 6 13:11:02 2007
@@ -21,7 +21,7 @@
/**
* Used to format messages used in errors and log output for classes within the impl package.
*
- * @author Howard Lewis Ship
+ * @author Achim Huegen
*/
class AnnotationsMessages
{
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Configuration.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Configuration.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Configuration.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Configuration.java Tue Feb 6 13:11:02 2007
@@ -9,7 +9,8 @@
/**
* Marks a method in an annotated module as configuration point.
* The return type of the method defines the configuration type.
- * The method is used factory method for the construction of the configuration container.
+ * The method is used as factory method for the construction of the configuration.
+ * It can return null if no initial contribution is to be provided.
*
* @author Achim Huegen
*/
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Contribution.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Contribution.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Contribution.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Contribution.java Tue Feb 6 13:11:02 2007
@@ -8,7 +8,9 @@
/**
* Marks a method in an annotated module as contribution to a configuration point.
- * The single parameter of the method must be compatible with the type of the configuration.
+ * The method can have one of two different signatures:
+ * 1. A void return type and a single parameter that must be compatible with the type of the configuration.
+ * 2. No parameter and a return type that must be compatible with the type of the configuration.
*
* @author Achim Huegen
*/
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Module.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Module.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Module.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Module.java Tue Feb 6 13:11:02 2007
@@ -7,8 +7,7 @@
import java.lang.annotation.Target;
/**
- * Marks a class as an annotated module and assigns an id
- * to it.
+ * Marks a class as an annotated module and assigns an id to it.
*
* @author Achim Huegen
*/
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Registry.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Registry.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Registry.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/Registry.java Tue Feb 6 13:11:02 2007
@@ -10,10 +10,45 @@
*/
public interface Registry
{
+ /**
+ * Returns a service from the registry.
+ *
+ * @see org.apache.hivemind.Registry#getService(String, Class)
+ */
public <T> T getService(String serviceId, Class<T> serviceInterface);
+
+ /**
+ * Finds a service that implements the provided interface.
+ * Exactly one such service may exist or an exception is thrown.
+ *
+ * @see org.apache.hivemind.Registry#getService(Class)
+ */
public <T> T getService(Class<T> serviceInterface);
+
+ /**
+ * Returns the specified configuration from the registry.
+ *
+ * @see org.apache.hivemind.Registry#getConfiguration(String)
+ */
public <T> T getConfiguration(String configurationId, Class<T> configurationType);
+
+ /**
+ * Finds a configuration by its type.
+ * Exactly one such configuration may exist or an exception is thrown.
+ *
+ * @see org.apache.hivemind.Registry#getConfiguration(String)
+ */
public <T> T getConfiguration(Class<T> configurationType);
+
+ /**
+ * Returns the specified configuration from the registry. The result is untyped.
+ *
+ * @see org.apache.hivemind.Registry#getConfiguration(String)
+ */
public Object getConfiguration(String configurationId);
+
+ /**
+ * Returns a reference to the {@link Autowiring} service.
+ */
public Autowiring getAutowiring();
}
Modified: hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/internal/RegistryImpl.java
URL: http://svn.apache.org/viewvc/hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/internal/RegistryImpl.java?view=diff&rev=504292&r1=504291&r2=504292
==============================================================================
--- hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/internal/RegistryImpl.java (original)
+++ hivemind/hivemind2/trunk/annotations/src/java/org/apache/hivemind/annotations/internal/RegistryImpl.java Tue Feb 6 13:11:02 2007
@@ -6,18 +6,32 @@
import org.apache.hivemind.service.Autowiring;
import org.apache.hivemind.util.IdUtils;
+/**
+ * Implementation of {@link Registry}.
+ * Wraps an instance of {@link RegistryInfrastructure} to provide registry access.
+ *
+ * @author Huegen
+ */
public class RegistryImpl implements Registry
{
private Module _callingModule;
private RegistryInfrastructure _delegate;
+ /**
+ * @param callingModule the module that gets access registry access by this instance.
+ * Used for visibility checks when services and configurations are retrieved.
+ * @param delegate
+ */
public RegistryImpl(Module callingModule, RegistryInfrastructure delegate)
{
_callingModule = callingModule;
_delegate = delegate;
}
+ /**
+ * @see org.apache.hivemind.annotations.Registry#getConfiguration(java.lang.String, java.lang.Class)
+ */
public <T> T getConfiguration(String configurationId, Class<T> configurationType)
{
String qualifiedConfigurationId = IdUtils.qualify(
@@ -29,13 +43,18 @@
return (T) configuration;
}
+ /**
+ * @see org.apache.hivemind.annotations.Registry#getConfiguration(java.lang.Class)
+ */
public <T> T getConfiguration(Class<T> configurationType)
{
- // Object configuration = _delegate.getConfiguration(configurationId, _callingModule);
- // throw new UnsupportedOperationException();
- return null;
+ Object configuration = _delegate.getConfiguration(configurationType, _callingModule);
+ return (T) configuration;
}
+ /**
+ * @see org.apache.hivemind.annotations.Registry#getConfiguration(java.lang.String)
+ */
public Object getConfiguration(String configurationId)
{
String qualifiedConfigurationId = IdUtils.qualify(
@@ -44,6 +63,9 @@
return _delegate.getConfiguration(qualifiedConfigurationId, _callingModule);
}
+ /**
+ * @see org.apache.hivemind.annotations.Registry#getService(java.lang.String, java.lang.Class)
+ */
public <T> T getService(String serviceId, Class<T> serviceInterface)
{
String qualifiedServiceId = IdUtils.qualify(
@@ -53,12 +75,18 @@
return (T) service;
}
+ /**
+ * @see org.apache.hivemind.annotations.Registry#getService(java.lang.Class)
+ */
public <T> T getService(Class<T> serviceInterface)
{
Object service = _delegate.getService(serviceInterface, _callingModule);
return (T) service;
}
+ /**
+ * @see org.apache.hivemind.annotations.Registry#getAutowiring()
+ */
public Autowiring getAutowiring()
{
return getService(Autowiring.class);