Author: mbenson
Date: Thu May 29 22:50:08 2014
New Revision: 1598436
URL: http://svn.apache.org/r1598436
Log:
[WEAVER-1] Enhance weaver documentation
Added:
commons/proper/weaver/trunk/src/site/resources/images/weaver.png (with
props)
commons/proper/weaver/trunk/src/site/resources/images/weaver.svg (with
props)
Modified:
commons/proper/weaver/trunk/src/site/markdown/index.md
Modified: commons/proper/weaver/trunk/src/site/markdown/index.md
URL:
http://svn.apache.org/viewvc/commons/proper/weaver/trunk/src/site/markdown/index.md?rev=1598436&r1=1598435&r2=1598436&view=diff
==============================================================================
--- commons/proper/weaver/trunk/src/site/markdown/index.md (original)
+++ commons/proper/weaver/trunk/src/site/markdown/index.md Thu May 29 22:50:08
2014
@@ -19,7 +19,6 @@ under the License.
# Apache Commons Weaver
-## What is this thing?
Occasionally, as Java developers, we encounter a problem whose solution
simply cannot be expressed in the Java language. Often, the Java annotation
processing tools can be used to great effect, and they should not be
@@ -28,36 +27,32 @@ classes. Occasionally, however, our only
class files. It is these situations which Apache Commons Weaver was designed
to address.
-Latest API documentation is [here](apidocs/index.html).
-
Apache Commons Weaver consists of:
-## Core Framework
+- Core Framework
+- Weaver Modules
+- Maven Plugin
+- Antlib
+
+The Maven Plugin and Antlib are used for invoking Weaving facilities. Below
you will
+find a graph with a high level overview of Apache Commons Weaver project.
+
+
+
+Latest API documentation is [here](apidocs/index.html).
+
+### Core Framework
The [Commons Weaver Processor](commons-weaver-processor/index.html)
defines a "weaver module" service provider interface (SPI) as well as
the facilities that use the Java `ServiceLoader` to discover and invoke
defined weaver modules for simple filesystem-based bytecode weaving.
-## Weaver Modules
+### Weaver Modules
A number of [Weaver Modules](commons-weaver-modules-parent/index.html)
are provided by the Commons Weaver project.
Typically a weaver module may respect a set of configuration
properties which should be documented along with that module.
-### What can these do for me?
-The canonical example is the [privilizer
module](commons-weaver-modules-parent/commons-weaver-privilizer-parent/index.html).
-
-## Integration
-The weaver module(s) applicable to your codebase should be available
-on the classpath of whatever Java-based processing mechanism you select.
-Your responsibilities are to:
-
- - trigger weave processing in some way
- - make the desired weaver module(s) available for processing
- - (optionally) provide configuration properties for applicable modules
-
-There are two provided mechanisms for invoking Weaving facilities:
-
### Maven Plugin
The [Commons Weaver plugin for Apache Maven][mvnplugin] aims to integrate
Weaver as smoothly as possible for Maven users. Here is an example
@@ -126,6 +121,125 @@ seen here:
Multiple weaving targets (e.g. `main` vs. `test`) are of course woven
using different `settings`.
+## Examples
+The canonical example is the [privilizer
module](commons-weaver-modules-parent/commons-weaver-privilizer-parent/index.html).
+
+A simple example could be exposing annotated methods for a REST API. Let's
suppose
+you want to expose only classes annotated with @WebExposed to your Web REST
API.
+
+ package example;
+
+ import java.lang.annotation.ElementType;
+ import java.lang.annotation.Retention;
+ import java.lang.annotation.RetentionPolicy;
+ import java.lang.annotation.Target;
+
+ /**
+ * Marks methods that interest our weaver module.
+ */
+ @Target(ElementType.METHOD)
+ @Retention(RetentionPolicy.CLASS)
+ public @interface WebExposed {
+
+ }
+
+And your POJO object annotated.
+
+ package example;
+
+ /**
+ * Represents a user in our system.
+ */
+ public class User implements {
+
+ private String name;
+ private String surname;
+ private Integer age;
+
+ public User() {
+ super();
+ }
+
+ public User(String name, String surname, Integer age) {
+ super();
+ this.name = name;
+ this.surname = surname;
+ this.age = age;
+ }
+
+ @WebExposed
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ @WebExposed
+ public String getSurname() {
+ return surname;
+ }
+
+ public void setSurname(String surname) {
+ this.surname = surname;
+ }
+
+ }
+
+
+Now in order to scan your classpath and find the annotated methods normally
you would
+use Java Reflection API or something similar, but the good news is that Apache
+Commons Weaver abstracts this for you.
+
+ package example;
+
+ import java.io.File;
+ import java.lang.annotation.ElementType;
+ import java.util.Arrays;
+ import java.util.Properties;
+
+ import org.apache.commons.weaver.WeaveProcessor;
+ import org.apache.commons.weaver.model.AnnotatedElements;
+ import org.apache.commons.weaver.model.ScanRequest;
+ import org.apache.commons.weaver.model.ScanResult;
+ import org.apache.commons.weaver.model.Scanner;
+ import org.apache.commons.weaver.model.WeavableMethod;
+ import org.apache.commons.weaver.model.WeaveEnvironment;
+ import org.apache.commons.weaver.model.WeaveInterest;
+ import org.apache.commons.weaver.spi.Weaver;
+
+ public class MyWeaver implements Weaver {
+
+ @Override
+ public boolean process(WeaveEnvironment environment, Scanner
scanner) {
+ // We want to find methods annotated with @WebExposed.
+ WeaveInterest findAnnotation =
WeaveInterest.of(WebExposed.class, ElementType.METHOD);
+ ScanResult scanResult = scanner.scan(new
ScanRequest().add(findAnnotation));
+ AnnotatedElements<WeavableMethod<?>> annotatedMethods =
scanResult.getMethods();
+ for (WeavableMethod<?> method : annotatedMethods) {
+ // The API code is out of the scope of this guide, but you
can do other things here,
+ // like modifying your class
+ System.out.println("Expose method " +
method.getTarget().getName() + " in our REST API");
+ }
+ return true;
+ }
+
+ public static void main(String[] args) {
+ // If you are using Maven, .. might resolve to your target
directory
+ File targetDir = new
File(MyWeaver.class.getResource("..").getFile());
+ //MyWeaver myWeaver = new MyWeaver();
+ WeaveProcessor weaveProcessor = new
WeaveProcessor(Arrays.asList("test.MyWeaver", "test.User"), targetDir, new
Properties());
+ weaveProcessor.weave();
+ }
+
+ }
+
+Before running the example above you need to tell the ServiceProvider about
+your custom Weaver. This is done by adding a file to your _META-INF_
directory.
+If you are using Maven, then creating
<code>src/main/resources/META-INF/services/org.apache.commons.weaver.spi.Weaver</code>
+with <pre>example.MyWeaver</pre> will instruct ServiceLoader to load your
Weaver class.
+
## Custom Weaver Modules
As discussed, some modules are provided for common cases, and the developers
welcome suggestions for useful modules, but there is no reason not to get
Added: commons/proper/weaver/trunk/src/site/resources/images/weaver.png
URL:
http://svn.apache.org/viewvc/commons/proper/weaver/trunk/src/site/resources/images/weaver.png?rev=1598436&view=auto
==============================================================================
Binary file - no diff available.
Propchange: commons/proper/weaver/trunk/src/site/resources/images/weaver.png
------------------------------------------------------------------------------
svn:executable = *
Propchange: commons/proper/weaver/trunk/src/site/resources/images/weaver.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: commons/proper/weaver/trunk/src/site/resources/images/weaver.svg
URL:
http://svn.apache.org/viewvc/commons/proper/weaver/trunk/src/site/resources/images/weaver.svg?rev=1598436&view=auto
==============================================================================
--- commons/proper/weaver/trunk/src/site/resources/images/weaver.svg (added)
+++ commons/proper/weaver/trunk/src/site/resources/images/weaver.svg Thu May 29
22:50:08 2014
@@ -0,0 +1,298 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/";
+ xmlns:cc="http://creativecommons.org/ns#";
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#";
+ xmlns:svg="http://www.w3.org/2000/svg";
+ xmlns="http://www.w3.org/2000/svg";
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd";
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape";
+ width="1052.3622"
+ height="600.09003"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="weaver.svg"
+ inkscape:export-filename="/home/kinow/Documents/weaver.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow1Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Lend"
+ style="overflow:visible">
+ <path
+ id="path3923"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.8,0,0,-0.8,-10,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="0.35"
+ inkscape:cx="372.60055"
+ inkscape:cy="569.17229"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1366"
+ inkscape:window-height="715"
+ inkscape:window-x="0"
+ inkscape:window-y="31"
+ inkscape:window-maximized="1" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage"; />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(0,-452.27218)">
+ <g
+ id="g5675"
+ transform="translate(-14.283447,148.48453)">
+ <g
+ transform="translate(96.432556,-68.571429)"
+ id="g3833">
+ <rect
+ style="fill:#aaccff;fill-rule:evenodd;stroke:none"
+ id="rect2985"
+ width="461.2854"
+ height="60.16766"
+ x="199.10583"
+ y="495.21933" />
+ <text
+ xml:space="preserve"
+
style="font-size:31.19804382px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="224.14305"
+ y="533.91003"
+ id="text3755"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3757"
+ x="224.14305"
+ y="533.91003">Apache Commons Weaver</tspan></text>
+ </g>
+ <g
+ transform="translate(48.571429,-63.171486)"
+ id="g3838">
+ <rect
+ style="fill:#aaccff;fill-rule:evenodd;stroke:none"
+ id="rect2985-7"
+ width="176.04611"
+ height="60.16766"
+ x="64.285698"
+ y="636.72473" />
+ <text
+ xml:space="preserve"
+
style="font-size:31.19804382px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="75.608482"
+ y="677.95941"
+ id="text3755-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="75.608482"
+ y="677.95941"
+ id="tspan3783">Processor</tspan></text>
+ </g>
+ <g
+ transform="translate(22.251709,-60.943093)"
+ id="g3853">
+ <rect
+ style="fill:#aaccff;fill-rule:evenodd;stroke:none"
+ id="rect2985-7-2"
+ width="176.04611"
+ height="60.16766"
+ x="296.0426"
+ y="634.49634" />
+ <text
+ xml:space="preserve"
+
style="font-size:31.19804382px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="318.44009"
+ y="676.21088"
+ id="text3755-1-8"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="318.44009"
+ y="676.21088"
+ id="tspan3783-4">Modules</tspan></text>
+ </g>
+ <g
+ transform="translate(136.06823,-317.21275)"
+ id="g3843">
+ <rect
+ style="fill:#aaccff;fill-rule:evenodd;stroke:none"
+ id="rect2985-7-6"
+ width="245.1275"
+ height="60.16766"
+ x="387.40829"
+ y="890.76599" />
+ <text
+ xml:space="preserve"
+
style="font-size:31.19804382px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="405.2804"
+ y="929.45667"
+ id="text3755-1-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="405.2804"
+ y="929.45667"
+ id="tspan3783-2">Maven Plugin</tspan></text>
+ </g>
+ <g
+ transform="translate(228.57143,-65.399941)"
+ id="g3848">
+ <rect
+ style="fill:#aaccff;fill-rule:evenodd;stroke:none"
+ id="rect2985-7-4"
+ width="176.04611"
+ height="60.16766"
+ x="563.45441"
+ y="638.95319" />
+ <text
+ xml:space="preserve"
+
style="font-size:31.19804382px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="606.96539"
+ y="680.66766"
+ id="text3755-1-84"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="606.96539"
+ y="680.66766"
+ id="tspan3783-9">Antlib</tspan></text>
+ </g>
+ <g
+ transform="translate(-20,-98.57143)"
+ id="g3909">
+ <rect
+ style="fill:#aaccff;fill-rule:evenodd;stroke:none"
+ id="rect2985-7-2-7"
+ width="198.90326"
+ height="60.16766"
+ x="465.85416"
+ y="819.4212" />
+ <text
+ xml:space="preserve"
+
style="font-size:31.19804382px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="478.7876"
+ y="861.13574"
+ id="text3755-1-8-9"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="478.7876"
+ y="861.13574"
+ id="tspan3783-4-2">Normalizer</tspan></text>
+ </g>
+ <g
+ transform="translate(20,-78.571429)"
+ id="g3904">
+ <rect
+ style="fill:#aaccff;fill-rule:evenodd;stroke:none"
+ id="rect2985-7-2-4"
+ width="176.04611"
+ height="60.16766"
+ x="174.83408"
+ y="799.4212" />
+ <text
+ xml:space="preserve"
+
style="font-size:31.19804382px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="195.01511"
+ y="841.13574"
+ id="text3755-1-8-8"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ x="195.01511"
+ y="841.13574"
+ id="tspan3783-4-3">Privilizer</tspan></text>
+ </g>
+ <path
+ transform="translate(0,308.2677)"
+ inkscape:connection-end-point="d4"
+ inkscape:connection-end="#g3838"
+ inkscape:connection-start-point="d4"
+ inkscape:connection-start="#g3833"
+ inkscape:connector-curvature="3"
+ inkscape:connector-type="polyline"
+ id="path3914"
+ d="M 459.56475,178.54786 267.49653,265.28555"
+
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
/>
+ <path
+ transform="translate(0,308.2677)"
+ inkscape:connection-end-point="d4"
+ inkscape:connection-end="#g3853"
+ inkscape:connection-start-point="d4"
+ inkscape:connection-start="#g3833"
+ inkscape:connector-curvature="3"
+ inkscape:connector-type="polyline"
+ id="path4364"
+ d="m 501.63495,178.54786 -70.77144,86.73768"
+
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
/>
+ <path
+ transform="translate(0,308.2677)"
+ inkscape:connection-end-point="d4"
+ inkscape:connection-end="#g3843"
+ inkscape:connection-start-point="d4"
+ inkscape:connection-start="#g3833"
+ inkscape:connector-curvature="3"
+ inkscape:connector-type="polyline"
+ id="path4736"
+ d="m 550.72631,178.54786 70.76875,86.73768"
+
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
/>
+ <path
+ transform="translate(0,308.2677)"
+ inkscape:connection-end-point="d4"
+ inkscape:connection-end="#g3848"
+ inkscape:connection-start-point="d4"
+ inkscape:connection-start="#g3833"
+ inkscape:connector-curvature="3"
+ inkscape:connector-type="polyline"
+ id="path4920"
+ d="m 598.64747,178.54786 208.93504,86.73769"
+
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
/>
+ <path
+ transform="translate(0,308.2677)"
+ inkscape:connection-end-point="d4"
+ inkscape:connection-end="#g3904"
+ inkscape:connection-start-point="d4"
+ inkscape:connection-start="#g3853"
+ inkscape:connector-curvature="3"
+ inkscape:connector-type="polyline"
+ id="path5288"
+ d="m 381.10186,325.4532 -73.02922,87.12887"
+
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
/>
+ <path
+ transform="translate(0,308.2677)"
+ inkscape:connection-end-point="d4"
+ inkscape:connection-end="#g3909"
+ inkscape:connection-start-point="d4"
+ inkscape:connection-start="#g3853"
+ inkscape:connector-curvature="3"
+ inkscape:connector-type="polyline"
+ id="path5472"
+ d="m 434.70435,325.4532 82.21445,87.12887"
+
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)"
/>
+ </g>
+ </g>
+</svg>
Propchange: commons/proper/weaver/trunk/src/site/resources/images/weaver.svg
------------------------------------------------------------------------------
svn:executable = *
