MHonArc v2.5.0b2 -->
docbook-tc message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Support for aspect oriented programming (aka annotations and attributes)Action Item
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 programmingThe 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() { … }
In the following text I will use word
aspect as a general name for both Java annotations
and C# attributes.
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 approachI 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.
|
S/MIME Cryptographic Signature
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]