Support for aspect oriented programming (aka annotations and attributes)

docbook-tc message

Subject: Support for aspect oriented programming (aka annotations and attributes)Action Item

From: Jirka Kosek <jirka@kosek.cz>

To: Bob Stayton <bobs@sagehill.net>

Date: Wed, 22 Feb 2006 22:44:18 +0100

Bob Stayton wrote: > 5. Review of open action items > > a. The Java language has added java annotations, and Norm > wondered how these would be marked up in a synopsis. > The C# language also has annotations, Jirka pointed out. > ACTION: Norm to investigate this issue some more. > Jirka will take over this action item. Here is my initial proposal for this action item. I'm attaching also HTML version of this text because it is easier to read. Comments welcomed. Adding support for aspect oriented programming into DocBook _________________________________________________________________ This document analyzes possible ways of implementing support for aspect oriented programming as requested by [1]RFE1306027. About aspect oriented programming The basic idea of Aspect Oriented Programming (AOP) is to specify auxiliary processing code (like logging or security checks) in a declarative way making code easier to read and focusing on the core problem. This idea was implemented into a mainstream languages like Java and C# during past years. Those languages allow you to specify metadata for each class, interface, method, property and so on. Such metadata can be used by various tools during compiling, application loading, at the runtime etc. depending on your needs. These metadata are generalization of modifiers like public, private, synchronized and final. The biggest difference is that metadata can be user defined and connected with user defined processing code and that they can take parameters. In Java such metadata are [2]called annotations in [3]C# attributes. Despite different names, semantics and behavior is almost the same. Java annotations are marked by starting @ character. There can be multiple annotations for one part of source code and annotations can take parameters (positional or named). Example 1. Annotations in Java @Deprecated public void doSomething() { ... } @TestParameters(testStage="Unit", testMethods="testConcat,testSubstring", testOutputType="screen", testOutput="") @Status("Doing something...") public String doSomethingElse(String a, String b) { ... } In C# attributes are placed inside square brackets. Several attributes can be specified together inside one single brackets, or they can be split to multiple square brackets. Attributes can take parameters (positional or named). Example 2. Attributes in C# [WebMethod(Description="Obtains the Server Machine Name", EnableSession=true)] [FileIOPermission(SecurityAction.Demand)] public string GetMachineName() { ... } [WebMethod(Description="Obtains the Server Machine Name", EnableSession=true), FileIOPermission(SecurityAction.Demand)] public string GetMachineName() { ... } Content model In the following text I will use word aspect as a general name for both Java annotations and C# attributes. Simplistic approach By nature aspect is just a special type of modifier. So it is possible to use existing modifier element to capture aspects. <classsynopsis> ... <methodsynopsis> <modifier>WebMethod(Description="Obtains the Server Machine Name", EnableSession=true), FileIOPermission(SecurityAction.Demand)</modifier> <modifier>public</modifier> <type>string</type> <methodname>GetMachineName</medhodname> ... </classsynopsis> The problem of this approach is the low level of semantics captured for aspects. Aspects can be compared to method calls and for method parameters there is a special markup in DocBook. Semantically rich approach I think that if we want to support aspects we should at least provide markup for capturing name of aspect and its parameters. There is however big difference between *synopsis elements and aspects - synopsises in DocBook are used to define type of something (be it function, class or method). In contrast aspects are more like instances - they contain actual metadata which should be associated with general type definitions. This means that aspect markup must be able to capture not parameter names and types, but parameter names and their values. I don't think that it is necessary to capture values of aspect parameters using special markup, but in this case aspect must allow mixed content. My proposal is to markup aspects in the following way: <classsynopsis> ... <methodsynopsis> <aspect><aspectname>WebMethod</aspectname>(<parameter>Description</paramete r>="Obtains the Server Machine Name", <parameter>EnableSession</parameter>=true)</aspect> <aspect><aspectname>FileIOPermission</aspectname>(SecurityAction.Demand)</a spect> <modifier>public</modifier> <type>string</type> <methodname>GetMachineName</medhodname> ... </classsynopsis> Content model of aspect element can be modeled as: # attributes are here just for completeness db.aspect.role.attribute = attribute role { text } db.aspect.attlist = db.aspect.role.attribute? & db.common.attributes & db.common.linking.attributes db.aspectname.role.attribute = attribute role { text } db.aspectname.attlist = db.aspectname.role.attribute? & db.common.attributes & db.common.linking.attributes # this is content model for new element db.aspect = element aspect { db.aspect.attlist, element aspectname { db.aspectname.attlist, db._text }, (element parameter { db.parameter.attlist, db._text }* & text) } Note Content model is only partially expanded and it is not following all currently used conventions to make it more readable and explicit. In the real schema there should be named pattern also for aspectname and parameter should be defined by reference to pattern db.parameter. Where aspects could appear? Essentially everywhere where modifier could appear. If we will choose aspect element, then it should be allowed zero or more times before modifier in synopsis elements. If the decision will be to use this more descriptive variant, we should consider in which particular types of synopsises it could appear. References 1. https://sourceforge.net/tracker/index.php?func=detail&aid=1306027&group_id=21935&atid=384107 2. http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html 3. http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-334.pdf#page=387 -- ------------------------------------------------------------------ Jirka Kosek e-mail: jirka@kosek.cz http://www.kosek.cz ------------------------------------------------------------------ Profesionální školení a poradenství v oblasti technologií XML. Podívejte se na náš nově spuštěný web http://DocBook.cz Podrobný přehled školení http://xmlguru.cz/skoleni/ ------------------------------------------------------------------ Nejbližší termíny školení: ** XSLT 13.-16.3.2006 ** XML schémata 24.-26.4.2006 ** ** DocBook 15.-17.5.2006 ** XSL-FO 12.-13.6.2006 ** ------------------------------------------------------------------

Title: Adding support for aspect oriented programming into DocBook

Adding support for aspect oriented programming into DocBook

This document analyzes possible ways of implementing support for aspect oriented programming as requested by RFE1306027.

About aspect oriented programming

The basic idea of Aspect Oriented Programming (AOP) is to specify auxiliary processing code (like logging or security checks) in a declarative way making code easier to read and focusing on the core problem. This idea was implemented into a mainstream languages like Java and C# during past years. Those languages allow you to specify metadata for each class, interface, method, property and so on. Such metadata can be used by various tools during compiling, application loading, at the runtime etc. depending on your needs. These metadata are generalization of modifiers like public, private, synchronized and final. The biggest difference is that metadata can be user defined and connected with user defined processing code and that they can take parameters.

In Java such metadata are called annotations in C# attributes. Despite different names, semantics and behavior is almost the same.

Java annotations are marked by starting @ character. There can be multiple annotations for one part of source code and annotations can take parameters (positional or named).

Example 1. Annotations in Java

@Deprecated public void doSomething() { … }

@TestParameters(testStage="Unit",
                testMethods="testConcat,testSubstring",
                testOutputType="screen",
                testOutput="")
@Status("Doing something...")
public String doSomethingElse(String a, String b) { … }

In C# attributes are placed inside square brackets. Several attributes can be specified together inside one single brackets, or they can be split to multiple square brackets. Attributes can take parameters (positional or named).

Example 2. Attributes in C#

[WebMethod(Description="Obtains the Server Machine Name",
           EnableSession=true)]
[FileIOPermission(SecurityAction.Demand)]
public string GetMachineName() { … }

[WebMethod(Description="Obtains the Server Machine Name",
           EnableSession=true), 
 FileIOPermission(SecurityAction.Demand)]
public string GetMachineName() { … }

Content model

In the following text I will use word aspect as a general name for both Java annotations and C# attributes.

Simplistic approach

By nature aspect is just a special type of modifier. So it is possible to use existing modifier element to capture aspects.

<classsynopsis>
  …
  <methodsynopsis>
    <modifier>WebMethod(Description="Obtains the Server Machine Name",
                        EnableSession=true), 
              FileIOPermission(SecurityAction.Demand)</modifier>
    <modifier>public</modifier> <type>string</type>
    <methodname>GetMachineName</medhodname>
  …
</classsynopsis>

The problem of this approach is the low level of semantics captured for aspects. Aspects can be compared to method calls and for method parameters there is a special markup in DocBook.

Semantically rich approach

I think that if we want to support aspects we should at least provide markup for capturing name of aspect and its parameters. There is however big difference between *synopsis elements and aspects – synopsises in DocBook are used to define type of something (be it function, class or method). In contrast aspects are more like instances – they contain actual metadata which should be associated with general type definitions. This means that aspect markup must be able to capture not parameter names and types, but parameter names and their values. I don't think that it is necessary to capture values of aspect parameters using special markup, but in this case aspect must allow mixed content.

My proposal is to markup aspects in the following way:

<classsynopsis>
  …
  <methodsynopsis>
    <aspect><aspectname>WebMethod</aspectname>(<parameter>Description</parameter>="Obtains the Server Machine Name",
                        <parameter>EnableSession</parameter>=true)</aspect>
    <aspect><aspectname>FileIOPermission</aspectname>(SecurityAction.Demand)</aspect>
    <modifier>public</modifier> <type>string</type>
    <methodname>GetMachineName</medhodname>
  …
</classsynopsis>

Content model of aspect element can be modeled as:

# attributes are here just for completeness
db.aspect.role.attribute = attribute role { text }
db.aspect.attlist =
    db.aspect.role.attribute?
    & db.common.attributes
    & db.common.linking.attributes

db.aspectname.role.attribute = attribute role { text }
db.aspectname.attlist =
    db.aspectname.role.attribute?
    & db.common.attributes
    & db.common.linking.attributes

# this is content model for new element
db.aspect = element aspect 
{ 
  db.aspect.attlist,
  element aspectname { db.aspectname.attlist, db._text },
  (element parameter { db.parameter.attlist, db._text }* & text)
}

Note

Content model is only partially expanded and it is not following all currently used conventions to make it more readable and explicit. In the real schema there should be named pattern also for aspectname and parameter should be defined by reference to pattern db.parameter.

Where aspects could appear?

Essentially everywhere where modifier could appear. If we will choose aspect element, then it should be allowed zero or more times before modifier in synopsis elements. If the decision will be to use this more descriptive variant, we should consider in which particular types of synopsises it could appear.