incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dk...@apache.org
Subject svn commit: r1478122 - in /sling/whiteboard/dklco/sling-proxy: ./ src/main/java/org/apache/sling/commons/proxy/annotations/ src/site/ src/site/markdown/
Date Wed, 01 May 2013 17:56:02 GMT
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:
- * 
- * &#64;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&lt;Resource&gt; getChildren();
+	
+    @SlingReference(returnType = ValueMap.class)
+    Iterator&lt;ValueMap&gt; getSubnodeProperties();
+    
+    @SlingReference(path = "/content/page", returnType=PageProxy.class)
+    Iterator&lt;IPageProxy&gt; 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>



Mime
View raw message