pt.digitalis.dif.dem
Class DEMAnnotationLogic

java.lang.Object
  extended by pt.digitalis.dif.dem.DEMAnnotationLogic

public class DEMAnnotationLogic
extends Object

Defines validation and enrichment logic for an annotationName or family of annotations. A set of methods validate general rules for any annotationName. Specific methods that can be overrided on sub-classes allow fine-grained validation rules. Methods that define the source code used on the code generation are also part of this class. TODO: Some logic that read the annotation values for processing is repeated here and in the ClassEnhancerImpl. Should be refactored for a single read operation. Maybe in 2.1 TODO: Making the xHolder classes inherit from a parent would eliminate the need of several similar methods with just different parameter types (as in validate() and validatePrimary()).

Author:
Pedro Viegas pviegas@digitalis.pt, Rodrigo Gonçalves rgoncalves@digitalis.pt, João Galaio jgalaio@digitalis.pt
Created on:
Aug 29, 2007

Field Summary
protected static String APPLICATION_ATTRIBUTE_NAME
          The 'application' attribute name.
static String DEFAULT_DEM_ANNOTATION_LOGIC_CLASS
          The the default DEM Annotation Logic class.
protected static String PROVIDER_ATTRIBUTE_NAME
          The 'provider' attribute name.
protected static String SERVICE_ATTRIBUTE_NAME
          The 'service' attribute name.
protected static String TARGET_ATTRIBUTE_NAME
          The 'target' attribute name.
 
Constructor Summary
DEMAnnotationLogic(String annotationFQName, String annotationName, boolean isPrimary)
          Constructor.
 
Method Summary
 void addSourceCodeForAnnotation(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation, ClassEnhancementContext classEnhancementContext)
          This method will define the code to enhance the classes based on the annotations.
 void addSourceCodeForAnnotation(ClassEnhancementContext classEnhancementContext, pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation, pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
          This method will define the code to enhance the attributes based on the annotations.
 void addSourceCodeForAnnotation(ClassEnhancementContext classEnhancementContext, pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation, pt.digitalis.utils.bytecode.holders.MethodHolder method)
          This method will define the code to enhance the methods based on the annotations.
protected  void addStage(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation, ClassEnhancementContext classEnhancementContext, boolean errorStage, boolean defaultStage, String attributeName)
          Adds an injected stage to the current stage to enhance.
protected  void addView(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation, ClassEnhancementContext classEnhancementContext, boolean errorView, boolean defaultView, String attributeName)
          Adds an injected view to the current stage to enhance.
protected  boolean checkUseWith(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotationToCheck, pt.digitalis.utils.bytecode.holders.AnnotationHolder thisAnnotation)
          Checks if a given annotation can be used with another.
 String getAnnotation()
          Returns the annotationName.
protected  IAuthorizationManager getAuthorizationManager()
           
protected  String getCodeForExecutionMethod(String signature, String methodName)
          Return the appropriated execute method call injecting a return view if necessary and the appropriated parameters
protected  boolean isDEMAnnotation()
           
 boolean isPrimary()
          Returns the value of the primary annotationName flag.
protected  boolean isPrimary(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation)
          Checks if a given annotation is primary.
static DEMAnnotationLogic makeObject(String annotationLogicClassName, pt.digitalis.utils.bytecode.holders.ClassHolder annotationClass)
          Factory method for DEMAnnotationLogic objects.
protected  Map<String,Object> prepareExceptionContext(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
          Prepares the exception context from the attribute.
protected  Map<String,Object> prepareExceptionContext(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
          Prepares the exception context from the class.
protected  Map<String,Object> prepareExceptionContext(pt.digitalis.utils.bytecode.holders.MethodHolder method)
          Prepares the exception context from the method.
 void setAnnotation(String newAnnotation)
          Sets the annotationName value.
protected  void validateDEMConsistency(String annotationName, pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
          Validates if the entities referred on the annotation parameters are valid on the DEM context.
protected  void validateMessages(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
          Validates if a given class message file exists.
protected  boolean validateNonPrivate(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
          Validates that the attribute is non-private.
protected  void validatePrimary(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
          Validates the use of primary annotations on a given attribute.
protected  void validatePrimary(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
          Validates the use of primary annotations on a given class.
protected  void validatePrimary(pt.digitalis.utils.bytecode.holders.MethodHolder method)
          Validates the use of primary annotations on a given method.
protected  boolean validateScope(String annotationName, pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
          Validates the usage scope of attribute annotations.
protected  boolean validateSpecificRules(String annotationName, pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
          Defines specific rules for applying the annotationName on a given attribute.
protected  boolean validateSpecificRules(String annotationName, pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
          Defines specific rules for applying the annotationName on a given class.
protected  boolean validateSpecificRules(String annotationName, pt.digitalis.utils.bytecode.holders.MethodHolder method)
          Defines specific rules for applying the annotationName on a given method.
 void validateUsage(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
          Validates the use of the annotation on a given attribute.
 void validateUsage(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
          Validates the use of the annotation on a given class.
 void validateUsage(pt.digitalis.utils.bytecode.holders.MethodHolder method)
          Validates the use of the annotation on a given method.
protected  void validateViewExistence(String attributeName, String className, Map<String,pt.digitalis.utils.bytecode.holders.AnnotationHolder> annotations)
          Checks if the received set of annotations contains the
protected  void warnOfEnityMisuseOnClass(String className, String entityName)
          Warns of an entity misuse on a given class.
protected  boolean yieldsTo(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation, String yieldToAnnotationName)
          Checks if a given primary annotation has the 'yieldTo' member value and if it contains a given annotation name.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

APPLICATION_ATTRIBUTE_NAME

protected static final String APPLICATION_ATTRIBUTE_NAME
The 'application' attribute name.

See Also:
Constant Field Values

DEFAULT_DEM_ANNOTATION_LOGIC_CLASS

public static final String DEFAULT_DEM_ANNOTATION_LOGIC_CLASS
The the default DEM Annotation Logic class.


PROVIDER_ATTRIBUTE_NAME

protected static final String PROVIDER_ATTRIBUTE_NAME
The 'provider' attribute name.

See Also:
Constant Field Values

SERVICE_ATTRIBUTE_NAME

protected static final String SERVICE_ATTRIBUTE_NAME
The 'service' attribute name.

See Also:
Constant Field Values

TARGET_ATTRIBUTE_NAME

protected static final String TARGET_ATTRIBUTE_NAME
The 'target' attribute name.

See Also:
Constant Field Values
Constructor Detail

DEMAnnotationLogic

public DEMAnnotationLogic(String annotationFQName,
                          String annotationName,
                          boolean isPrimary)
Constructor.

Parameters:
annotationFQName - the annotation fully qualified name
annotationName - the annotation simple name
isPrimary - T if annotation is primary, F otherwise
Method Detail

makeObject

public static DEMAnnotationLogic makeObject(String annotationLogicClassName,
                                            pt.digitalis.utils.bytecode.holders.ClassHolder annotationClass)
                                     throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException,
                                            pt.digitalis.utils.inspection.exception.AuxiliaryOperationException
Factory method for DEMAnnotationLogic objects. Gets the name of a DEMAnnotationLogic subtype and generates the appropriate object. Encapsulates the complex code used to create the objects by reflection. This method's client is the pt.digitalis.dif.codegen.util.DEMLoaderHelper#getAnnotationLogicMap() which generates a map whose values are DEMAnnotationLogic subclasses. These values can't be inserted on the map if they belong to a runtime determined type.

Parameters:
annotationLogicClassName - The name of the annotationName logic class
annotationClass - The argument annotationName
Returns:
a new DEMAnnotationLogic instance of the appropriate subclass
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any needed class cannot be found
pt.digitalis.utils.inspection.exception.AuxiliaryOperationException - if any illegal operation or instantiation exceptions are raised

addSourceCodeForAnnotation

public void addSourceCodeForAnnotation(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation,
                                       ClassEnhancementContext classEnhancementContext)
                                throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException,
                                       DIFCodeGenerationException
This method will define the code to enhance the classes based on the annotations. It will create the appropriate methods and their code and add them to the classEnhancement object.

Parameters:
classEnhancementContext - the class enhancement context
annotation - the annotation used to define the source code needed for enhancement
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if annotation members can't be accessed
DIFCodeGenerationException

addSourceCodeForAnnotation

public void addSourceCodeForAnnotation(ClassEnhancementContext classEnhancementContext,
                                       pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation,
                                       pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
                                throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException,
                                       DIFCodeGenerationException
This method will define the code to enhance the attributes based on the annotations. It will create the appropriate methods and their code and add them to the classEnhancement object.

Parameters:
classEnhancementContext - the class enhancement context
annotation - the annotation used to define the source code needed for enhancement
attribute - the attribute to be enhanced (to make the context available to the source building process)
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if annotation members can't be accessed
DIFCodeGenerationException

addSourceCodeForAnnotation

public void addSourceCodeForAnnotation(ClassEnhancementContext classEnhancementContext,
                                       pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation,
                                       pt.digitalis.utils.bytecode.holders.MethodHolder method)
                                throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException,
                                       DIFCodeGenerationException
This method will define the code to enhance the methods based on the annotations. It will create the appropriate methods and their code and add them to the classEnhancement object.

Parameters:
classEnhancementContext - the class enhancement context
annotation - the annotation used to define the source code needed for enhancement
method - the method to be enhanced (to make the context available to the source building process)
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if annotation members can't be accessed
DIFCodeGenerationException

addStage

protected void addStage(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation,
                        ClassEnhancementContext classEnhancementContext,
                        boolean errorStage,
                        boolean defaultStage,
                        String attributeName)
                 throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException,
                        DIFCodeGenerationException
Adds an injected stage to the current stage to enhance. Injects it the the attribute associated (if passed) and to the inner Maps.

Parameters:
annotation - the annotation that declared the stage
classEnhancementContext - the class enhancement context
errorStage - if the stage to add is an error stage
defaultStage - if the current stage is the default stage
attributeName - the name of the attribute to assign the new stage to
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if the annotation cannot be read
DIFCodeGenerationException

addView

protected void addView(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation,
                       ClassEnhancementContext classEnhancementContext,
                       boolean errorView,
                       boolean defaultView,
                       String attributeName)
                throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException,
                       DIFCodeGenerationException
Adds an injected view to the current stage to enhance. Injects it the the attribute associated (if passed) and to the inner Maps.

Parameters:
annotation - the annotation that declared the stage
classEnhancementContext - the class enhancement context
errorView - if the view to add is an error view
defaultView - if the view to add is the default stage view
attributeName - the name of the attribute to assign the new view to
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if the annotation cannot be read
DIFCodeGenerationException

checkUseWith

protected boolean checkUseWith(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotationToCheck,
                               pt.digitalis.utils.bytecode.holders.AnnotationHolder thisAnnotation)
                        throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Checks if a given annotation can be used with another.

Parameters:
annotationToCheck - the annotation to check
thisAnnotation - the annotation to validate against
Returns:
F if the annotation to check is primary and doesn't yield to the other, T otherwise
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for validation could not be found.

getAnnotation

public String getAnnotation()
Returns the annotationName.

Returns:
the value of the annotationName

getAuthorizationManager

protected IAuthorizationManager getAuthorizationManager()
Returns:
the authorizationManager

getCodeForExecutionMethod

protected String getCodeForExecutionMethod(String signature,
                                           String methodName)
Return the appropriated execute method call injecting a return view if necessary and the appropriated parameters

Parameters:
signature - the method to call signature
methodName - the method name to call
Returns:
the line of code for the calling of the method

isDEMAnnotation

protected boolean isDEMAnnotation()
Returns:
T if the current annotation is a DEM annotation

isPrimary

public final boolean isPrimary()
Returns the value of the primary annotationName flag.

Returns:
T if the annotationName is primary, F otherwise

isPrimary

protected boolean isPrimary(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation)
                     throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Checks if a given annotation is primary.

Parameters:
annotation - the annotation to check
Returns:
T if annotation is meta-annotated with @Primary, F otherwise.
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if meta-annotations can't be found

prepareExceptionContext

protected Map<String,Object> prepareExceptionContext(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
Prepares the exception context from the attribute.

Parameters:
attribute - the class object
Returns:
the exception context

prepareExceptionContext

protected Map<String,Object> prepareExceptionContext(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
Prepares the exception context from the class.

Parameters:
clazz - the class object
Returns:
the exception context

prepareExceptionContext

protected Map<String,Object> prepareExceptionContext(pt.digitalis.utils.bytecode.holders.MethodHolder method)
Prepares the exception context from the method.

Parameters:
method - the class object
Returns:
the exception context

setAnnotation

public void setAnnotation(String newAnnotation)
Sets the annotationName value.

Parameters:
newAnnotation - the new annotationName value

validateDEMConsistency

protected void validateDEMConsistency(String annotationName,
                                      pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
                               throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates if the entities referred on the annotation parameters are valid on the DEM context.

Parameters:
annotationName - the name of the annotation to validate
clazz - the class holder
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for the validation can't be found

validateMessages

protected void validateMessages(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
                         throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates if a given class message file exists. Only works if DiF is in DEBUG mode.

Parameters:
clazz - the class to validate the messages *
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for the validation can't be found

validateNonPrivate

protected boolean validateNonPrivate(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
Validates that the attribute is non-private.

Parameters:
attribute - the attribute to validate
Returns:
T if the attribute is non-private, F otherwise

validatePrimary

protected void validatePrimary(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
                        throws AnnotationMisuseException,
                               pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates the use of primary annotations on a given attribute.

Parameters:
attribute - the attribute to search for primary annotations
Throws:
AnnotationMisuseException - if an annotation is misused
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for validation could not be found.

validatePrimary

protected void validatePrimary(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
                        throws AnnotationMisuseException,
                               pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates the use of primary annotations on a given class.

Parameters:
clazz - the class to search for primary annotations
Throws:
AnnotationMisuseException - if an annotation is misused
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for validation could not be found.

validatePrimary

protected void validatePrimary(pt.digitalis.utils.bytecode.holders.MethodHolder method)
                        throws AnnotationMisuseException,
                               pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates the use of primary annotations on a given method.

Parameters:
method - the method to search for primary annotations
Throws:
AnnotationMisuseException - if an annotation is misused
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for validation could not be found.

validateScope

protected boolean validateScope(String annotationName,
                                pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
                         throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates the usage scope of attribute annotations.

Parameters:
annotationName - the name of the annotation to validate
attribute - the attribute to validate
Returns:
T if the scope is correct, F otherwise
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for the validation can't be found

validateSpecificRules

protected boolean validateSpecificRules(String annotationName,
                                        pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
                                 throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Defines specific rules for applying the annotationName on a given attribute. Returns T by default.

Parameters:
attribute - the annotated attribute
annotationName - the annotationName
Returns:
T if all conditions are verified, F otherwise
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException

validateSpecificRules

protected boolean validateSpecificRules(String annotationName,
                                        pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
                                 throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Defines specific rules for applying the annotationName on a given class. Returns T by default.

Parameters:
annotationName - the annotationName
clazz - the annotated class
Returns:
T if all conditions are verified, F otherwise
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any needed resource for validation is not found

validateSpecificRules

protected boolean validateSpecificRules(String annotationName,
                                        pt.digitalis.utils.bytecode.holders.MethodHolder method)
                                 throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Defines specific rules for applying the annotationName on a given method. Returns T by default.

Parameters:
method - the annotated method
annotationName - the annotationName
Returns:
T if all conditions are verified, F otherwise
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException

validateUsage

public final void validateUsage(pt.digitalis.utils.bytecode.holders.AttributeHolder attribute)
                         throws AnnotationMisuseException,
                                pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates the use of the annotation on a given attribute. Validation includes checking if multiple primary annotations are used, if the scope is correct, if the annotation members provide information consistent with the DEM and if any other specific rules apply.

Parameters:
attribute - the attribute on which the annotationName is used
Throws:
AnnotationMisuseException - if an inappropriate annotation usage was made
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for the validation can't be found

validateUsage

public final void validateUsage(pt.digitalis.utils.bytecode.holders.ClassHolder clazz)
                         throws AnnotationMisuseException,
                                pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates the use of the annotation on a given class. Validation includes checking if multiple primary annotations are used, if the scope is correct, if the annotation members provide information consistent with the DEM and if any other specific rules apply.

Parameters:
clazz - the class on which the annotation is used
Throws:
AnnotationMisuseException - if an inappropriate annotation usage was made
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for the validation can't be found

validateUsage

public final void validateUsage(pt.digitalis.utils.bytecode.holders.MethodHolder method)
                         throws AnnotationMisuseException,
                                pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Validates the use of the annotation on a given method. Validation includes checking if multiple primary annotations are used, if the scope is correct and if any other specific rules apply.

Parameters:
method - the method on which the annotation is used
Throws:
AnnotationMisuseException - if an inappropriate annotation usage was made
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for the validation can't be found

validateViewExistence

protected void validateViewExistence(String attributeName,
                                     String className,
                                     Map<String,pt.digitalis.utils.bytecode.holders.AnnotationHolder> annotations)
                              throws pt.digitalis.utils.inspection.exception.ResourceNotFoundException
Checks if the received set of annotations contains the

Parameters:
attributeName - the name of the annotated attribute if it exists
className - the name of the annotated class or the attribute's class name
annotations - the annotation set to validate
Throws:
pt.digitalis.utils.inspection.exception.ResourceNotFoundException - if any resource needed for the validation can't be found

warnOfEnityMisuseOnClass

protected void warnOfEnityMisuseOnClass(String className,
                                        String entityName)
Warns of an entity misuse on a given class.

Parameters:
className - the name of the class where the reference is being made
entityName - the name of the referred entity

yieldsTo

protected boolean yieldsTo(pt.digitalis.utils.bytecode.holders.AnnotationHolder annotation,
                           String yieldToAnnotationName)
Checks if a given primary annotation has the 'yieldTo' member value and if it contains a given annotation name.

Parameters:
annotation - the primary annotation to check
yieldToAnnotationName - the name on the 'yieldTo' value
Returns:
T if the primary annotation yields to the passed name, F otherwise


Copyright © 2014 Digitalis Informática Lda. All Rights Reserved.