Author: dklco
Date: Wed May 1 17:56:01 2013
New Revision: 1478122
URL: http://svn.apache.org/r1478122
Log:
Updated the documentation somewhat and added the basis for a maven generated
site
Added:
sling/whiteboard/dklco/sling-proxy/src/site/markdown/
sling/whiteboard/dklco/sling-proxy/src/site/markdown/annotations.md
sling/whiteboard/dklco/sling-proxy/src/site/markdown/index.md
sling/whiteboard/dklco/sling-proxy/src/site/site.xml
Removed:
sling/whiteboard/dklco/sling-proxy/src/site/proxy.mdtext
Modified:
sling/whiteboard/dklco/sling-proxy/pom.xml
sling/whiteboard/dklco/sling-proxy/src/main/java/org/apache/sling/commons/proxy/annotations/SlingProperty.java
Modified: sling/whiteboard/dklco/sling-proxy/pom.xml
URL:
http://svn.apache.org/viewvc/sling/whiteboard/dklco/sling-proxy/pom.xml?rev=1478122&r1=1478121&r2=1478122&view=diff
==============================================================================
--- sling/whiteboard/dklco/sling-proxy/pom.xml (original)
+++ sling/whiteboard/dklco/sling-proxy/pom.xml Wed May 1 17:56:01 2013
@@ -47,7 +47,62 @@
</instructions>
</configuration>
</plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>3.0</version>
+ <dependencies>
+ <dependency>
+
<groupId>org.apache.maven.doxia</groupId>
+
<artifactId>doxia-module-markdown</artifactId>
+ <version>1.3</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <reportPlugins>
+ <plugin>
+
<groupId>org.apache.maven.plugins</groupId>
+
<artifactId>maven-changes-plugin</artifactId>
+ <version>2.9</version>
+ <reportSets>
+ <reportSet>
+
<reports>
+
<report>changes-report</report>
+
</reports>
+ </reportSet>
+ </reportSets>
+ <configuration>
+
<issueManagementSystems>
+
<issueManagementSystem>JIRA</issueManagementSystem>
+
</issueManagementSystems>
+ </configuration>
+ </plugin>
+ <plugin>
+
<groupId>org.apache.maven.plugins</groupId>
+
<artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.2</version>
+ <reportSets>
+ <reportSet>
+
<reports>
+
<report>index</report>
+
<report>help</report>
+
<report>summary</report>
+
<report>license</report>
+
<report>dependencies</report>
+
</reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ <plugin>
+
<groupId>org.apache.maven.plugins</groupId>
+
<artifactId>maven-javadoc-plugin</artifactId>
+ <version>2.9</version>
+ </plugin>
+ </reportPlugins>
+ </configuration>
+ </plugin>
</plugins>
+
</build>
<reporting>
<plugins>
Modified:
sling/whiteboard/dklco/sling-proxy/src/main/java/org/apache/sling/commons/proxy/annotations/SlingProperty.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/dklco/sling-proxy/src/main/java/org/apache/sling/commons/proxy/annotations/SlingProperty.java?rev=1478122&r1=1478121&r2=1478122&view=diff
==============================================================================
---
sling/whiteboard/dklco/sling-proxy/src/main/java/org/apache/sling/commons/proxy/annotations/SlingProperty.java
(original)
+++
sling/whiteboard/dklco/sling-proxy/src/main/java/org/apache/sling/commons/proxy/annotations/SlingProperty.java
Wed May 1 17:56:01 2013
@@ -25,31 +25,10 @@ import java.lang.annotation.RetentionPol
import java.lang.annotation.Target;
/**
- * Annotation used to mark a Method as being a JCR backed property. All JCR
- * backed methods must use JavaBean style naming to identify them as either a
- * 'getter' (getSomeValue, isSomevalue) or a JavaBean 'setter' 'setSomeValue'.
+ * Annotation used to mark a Method as being a JCR backed property.
*
- * 'name' and 'path' are both optional. If both are missing and/or empty, then
- * the method name will be used to determine the corresponding JCR property
- * name. In this case, namespaced property names are handled this way:
- *
- * @SlingProperty<br/>
- * Date getCq_lastReplicated();
- *
- * this will correspond to a JCR property name of: 'cq:lastReplicated'
- *
- * The ":" in the property name must be represented as a "_" underscore in the
- * Property name.
- *
- * This style of property name identification will limit properties to being
- * located immediately within the associated Resource Object.
- *
- * It is recommended to use 'name' and 'path' values as this enables the use of
- * extravagant property names located anywhere within the JCR, not simply
within
- * the current Resource.
- *
- * Property names starting with '/' are absolute references, and do not have to
- * be contained beneath the current Resource. Property names not starting with
+ * Paths starting with '/' are absolute references, and do not have to
+ * be contained beneath the current Resource. Paths not starting with
* '/' are assumed to be relative to the current Resource.
*
* Here are 3 examples, one of each style:
@@ -86,8 +65,7 @@ public @interface SlingProperty {
byte[] defaultBytes() default {};
/**
- * The default date, used to set the default value for Calendars, Dates
&
- * Long Timestamps.
+ * The default date, used to set the default value for Calendars and
Dates.
*
* @return the default date
*/
Added: sling/whiteboard/dklco/sling-proxy/src/site/markdown/annotations.md
URL:
http://svn.apache.org/viewvc/sling/whiteboard/dklco/sling-proxy/src/site/markdown/annotations.md?rev=1478122&view=auto
==============================================================================
--- sling/whiteboard/dklco/sling-proxy/src/site/markdown/annotations.md (added)
+++ sling/whiteboard/dklco/sling-proxy/src/site/markdown/annotations.md Wed May
1 17:56:01 2013
@@ -0,0 +1,120 @@
+# Apache Sling Proxy - Annotations
+
+Three annotations are provided to annotation Proxy Interface methods.
+
+## SlingChildren
+
+Annotation used to mark a Method as retrieving the children of a resource. The
path is not required. If you do not specify a path the children of the proxied
resource will be retrieved. Paths starting with '/' are absolute references,
and do not have to be contained beneath the current Resource. Paths not
starting with '/' are assumed to be relative to the current Resource.
+
+The child Resources at the path will be returned as an Iterator of either a
resource or the type specified in the returnType property, according to the
following rules (in order):
+
+
+* If the return type is an instance of a Resource, the resource at the path
will be returned
+* If adapting the resource into the return class returns a non-null, this
object will be returned
+* If using the ProxyService to retrieve a proxy instance does not throw and
error and does not return null, the resulting object will returned
+* Otherwise, null will be returned
+
+Here are 3 examples, showing valid usages:
+
+ @SlingChildren(path = "jcr:content")
+ Iterator<Resource> getChildren();
+
+ @SlingReference(returnType = ValueMap.class)
+ Iterator<ValueMap> getSubnodeProperties();
+
+ @SlingReference(path = "/content/page", returnType=PageProxy.class)
+ Iterator<IPageProxy> getSubPageProxes();
+
+### Parameters
+
+The following parameters can be specified to configure the `@SlingChildren`
annotation processing.
+
+| Name | Description | Type | Default |
+|--|--|--|--|
+| path | The path to the child Resources to retrieve, if it begins with '/' it
will be treated as an absolute path, otherwise, it will be treated as a
relative path. | String | "" |
+| returnType | The type to be returned as the generic type in the iterator. |
Class | `Resource` |
+
+## SlingProperty
+
+Annotation used to mark a Method as being a JCR backed property. Either a
`path` or `name` must be specified in order to locate the appropriate property
to retrieve. Paths starting with '/' are absolute references, and do not have
to be contained beneath the current `Resource`. `Paths` not starting with '/'
are assumed to be relative to the current `Resource`.
+
+Here are 3 examples of simple retrieval, one of each style:
+
+ @SlingProperty(name = "cq:lastReplicated")<br/>
+ Date getLastReplicated();
+
+ @SlingProperty(path = "par/image", name = "fileReference")<br/>
+ String getImagePath();
+
+
@SlingProperty(path="/content/dam/geometrixx/documents/GeoCube_Datasheet.pdf/jcr:content/renditions/original/jcr:content",
name="jcr:data")<br/>
+ InputStream getGeoCubePDF();
+
+### Defaults
+
+Developers can specify a default value to be returned for many return types.
Using this option, the return value is casted into the same class as the method
return, and a default is specified in the annotation configuration if no value
is found.
+
+To use a default, add the parameter `useDefault=true` to a `@SlingProperty`
annotation and add the corresponding default parameter for the method return
type.
+
+The following return types are supported with default values:
+
+| Type | Parameter |
+|--|--|--|--|
+| Boolean | defaultBoolean |
+| boolean | defaultBoolean |
+| Byte[] | defaultBytes |
+| byte[] | defaultBytes |
+| InputStream | defaultBytes |
+| Calendar | defaultDate |
+| Date | defaultDate |
+| Double | defaultDouble |
+| String | defaultString |
+| String[] | defaultStrings |
+
+If the method does not have a valid return type, the value be retrieved
without the default and null may be returned.
+
+### Parameters
+
+The following parameters can be specified for the `@SlingProperty` annotation
to configure how the properties is retrieved.
+
+| Name | Description | Type | Default |
+|--|--|--|--|
+| defaultBoolean | Sets the default for methods which return booleans. |
boolean | false |
+| defaultBytes | Sets the default when the method returns an InputStream or a
byte array. | byte[] | byte[0] |
+| defaultDate | Sets the default value for methods which return Calendars or
Dates | long | -1L |
+| defaultDouble | Sets the default value for methods which return doubles. |
double | 0.0 |
+| defaultLong | Sets the default value for methods which return longs. | long
| 0L |
+| defaultString | Sets the default value for methods which return a String. |
String | |
+| defaultStrings | Sets the default value for methods which return a String
array. | String | String[0] |
+| name | The name of the property to retrieve from Sling. | String | |
+| path | The path to the property to retrieve, if it begins with '/' it will
be treated as an absolute path, otherwise, it will be treated as a relative
path. | String | |
+| useDefault | A flag indicate that Sling Proxy should use a default value
instead of just casting the return value. | boolean | false |
+
+## SlingReference
+
+Annotation used to mark a Method as referencing another resource. The path is
required paths starting with '/' are absolute references, and do not have to be
contained beneath the current Resource. Paths not starting with '/' are assumed
to be relative to the current Resource.
+
+The Resource at the path will be returned depending on the return type of the
method, according to the following rules (in order):
+
+* If the return type is an instance of a Resource, the resource at the path
will be returned
+* If adapting the resource into the return class returns a non-null, this
object will be returned
+* If using the ProxyService to retrieve a proxy instance does not throw and
error and does not return null, the resulting object will returned
+* Otherwise, null will be returned
+
+Here are 3 examples, showing valid return types:
+
+ @SlingReference(path = "/content/page")
+ Resource getPage();
+
+ @SlingReference(path = "/content/page")
+ ValueMap getPageProperties();
+
+ @SlingReference(path = "/content/page")
+ IPageProxy getPageProxy();
+
+### Parameters
+
+The following parameters can be specified for the `@SlingReference` annotation
to configure how the properties is retrieved.
+
+| Name | Description | Type | Default |
+|--|--|--|--|
+| path | The path to the resource being referenced, if it begins with '/' it
will be treated as an absolute path, otherwise, it will be treated as a
relative path. | String | |
\ No newline at end of file
Added: sling/whiteboard/dklco/sling-proxy/src/site/markdown/index.md
URL:
http://svn.apache.org/viewvc/sling/whiteboard/dklco/sling-proxy/src/site/markdown/index.md?rev=1478122&view=auto
==============================================================================
--- sling/whiteboard/dklco/sling-proxy/src/site/markdown/index.md (added)
+++ sling/whiteboard/dklco/sling-proxy/src/site/markdown/index.md Wed May 1
17:56:01 2013
@@ -0,0 +1,31 @@
+# Apache Sling Proxy
+
+Sling Proxy allows you to develop interfaces which will be instantiated with
properties from the Sling repository at runtime. Sling Proxy uses the [Java
Dynamic Proxies
API](http://docs.oracle.com/javase/1.4.2/docs/guide/reflection/proxy.html) to
dynamically handle method calls against the interface. The Sling Proxy API
allows you to avoid having to write custom code to handle the mapping of Sling
properties to Java fields allowing you to spend less time on boilerplate code
and more on your application.
+
+## Creating a Sling Proxy
+
+To create a Sling Proxy, simply create an interface which extends the
SlingProxy interface. All methods on the interface should be annotated with
one of the [Sling Proxy Annotations](annotations.html)
+
+## Retrieving a Sling Proxy Instance
+
+To retrieve a Sling Proxy instance, retrieve a reference to the
SlingProxyService. This service has one method, getProxy, which allows you to
retrieve a proxy implemetation:
+
+ SlingProxyService slingProxyService =
sling.getService(SlingProxyService.class);
+ MySlingProxy mySlingProxy = slingProxyService.getProxy(resource,
MySlingProxy.class);
+
+## Making your Sling Proxy adaptable
+
+Using the SlingProxyService is convenient, but with a little more code, you
can adapt Sling Resources directly to your Proxy interfaces. To enable
adapting resources to your proxy interfaces, create a AdapterFactory service,
which extends the AbstractProxyAdapterFactory class. For example:
+
+ @Component(label = "File Proxy Adapter Factory", name =
"org.apache.sling.commons.proxy.test.FileProxyAdapterFactory", metatype = true,
immediate = true)
+ @Service(value = AdapterFactory.class)
+ @Properties(value = {
+ @Property(name = AdapterFactory.ADAPTABLE_CLASSES, value =
"org.apache.sling.api.resource.Resource"),
+ @Property(name = AdapterFactory.ADAPTER_CLASSES, value =
"org.apache.sling.commons.proxy.test.FileProxy"),
+ @Property(name = "service.vendor", value = "The Apache Software
Foundation"),
+ @Property(name = "service.description", value = "File Proxy
Adapter Factory") })
+ public class FileProxyAdapterFactory extends AbstractProxyAdapterFactory {
+
+ }
+
+The AbstractProxyAdapterFactory will automatically handle the default
behavior, but you can of course override the default behavior to support more
adaptables or perform pre/post-processing.
\ No newline at end of file
Added: sling/whiteboard/dklco/sling-proxy/src/site/site.xml
URL:
http://svn.apache.org/viewvc/sling/whiteboard/dklco/sling-proxy/src/site/site.xml?rev=1478122&view=auto
==============================================================================
--- sling/whiteboard/dklco/sling-proxy/src/site/site.xml (added)
+++ sling/whiteboard/dklco/sling-proxy/src/site/site.xml Wed May 1 17:56:01
2013
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!-- /** * Copyright 2006 The Apache Software Foundation. * * Licensed under
+ the Apache License, Version 2.0 (the "License"); * you may not use this
file
+ except in compliance with the License. * You may obtain a copy of the
License
+ at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required
by
+ applicable law or agreed to in writing, software * distributed under
the
+ License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR
CONDITIONS
+ OF ANY KIND, either express or implied. * See the License for the
specific
+ language governing permissions and * limitations under the License. */
-->
+<project xmlns="http://maven.apache.org/DECORATION/1.3.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/DECORATION/1.3.0
http://maven.apache.org/xsd/decoration-1.3.0.xsd";>
+ <body>
+ <menu name="Overview">
+ <item name="Introduction" href="index.html" />
+ <item name="Annotations" href="annotations.html" />
+ </menu>
+ <menu ref="reports" />
+ </body>
+ <version position="right" />
+ <publishDate position="right" />
+ <skin>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>org.apache.sling.site.bundle-skin</artifactId>
+ <version>0.0.1-SNAPSHOT</version>
+ </skin>
+</project>
