Improve documentation

git-svn-id: https://svn.argeo.org/slc/trunk@2522 4cfe0d0a-d680-48aa-b62c-e0a02a3f76cc

diff --git a/pom.xml b/pom.xml
index d718ce24ebe2a7040833b8906ab28f3462538db6..b6274b43909e4387f002c15beb80c93be2c25fb6 100644 (file)
--- a/pom.xml
+++ b/pom.xml
@@ -27,7 +27,7 @@
                <version.equinox>3.4.2.R34x_v20080826-1230</version.equinox>
                <version.maven-bundle-plugin>2.0.0</version.maven-bundle-plugin>
                <version.activemq>5.2.0.0006</version.activemq>
                <version.equinox>3.4.2.R34x_v20080826-1230</version.equinox>
                <version.maven-bundle-plugin>2.0.0</version.maven-bundle-plugin>
                <version.activemq>5.2.0.0006</version.activemq>

-               <version.maven-argeo-osgi>0.1.12</version.maven-argeo-osgi>
+               <version.maven-argeo-osgi>0.1.13</version.maven-argeo-osgi>

                <site.repoBase>file:///var/argeo/projects/SLC/www/site</site.repoBase>
                <site.urlBase>http://www.argeo.org/projects/slc/site</site.urlBase>
        </properties>
                <site.repoBase>file:///var/argeo/projects/SLC/www/site</site.repoBase>
                <site.urlBase>http://www.argeo.org/projects/slc/site</site.urlBase>
        </properties>


@@ -604,6 +604,11 @@ limitations under the License.
                                <artifactId>org.argeo.dep.osgi.commons.cli</artifactId>
                                <version>1.1</version>
                        </dependency>
                                <artifactId>org.argeo.dep.osgi.commons.cli</artifactId>
                                <version>1.1</version>
                        </dependency>

+                       <dependency>
+                               <groupId>org.argeo.dep.osgi</groupId>
+                               <artifactId>org.argeo.dep.osgi.commons.exec</artifactId>
+                               <version>1.0.0.argeo1</version>
+                       </dependency>

                        <dependency>
                                <groupId>org.apache.commons</groupId>
                                <artifactId>com.springsource.org.apache.commons.pool</artifactId>
                        <dependency>
                                <groupId>org.apache.commons</groupId>
                                <artifactId>com.springsource.org.apache.commons.pool</artifactId>

diff --git a/src/site/apt/howtos/howto-attachments.apt b/src/site/apt/howtos/howto-attachments.apt
new file mode 100644 (file)
index 0000000..1df2adc
--- /dev/null
+++ b/src/site/apt/howtos/howto-attachments.apt
@@ -0,0 +1,94 @@
+Upload of attachments to a test result
+
+       This allows to attach ANY Spring resource (for example the one created above but not only, since it can also be classpath: or osgibundle: Resources or ANY file on the file system where the agent is running (e.g. Mx *.mxres files on a server...))
+       
+       In order to use it:
+       
+       [[1]] First reference an attachment uploader service via OSGi (it is provided by the standard agent):
+       
++-------------------------------+
+<reference id="attachmentUploader" interface="org.argeo.slc.core.attachment.AttachmentUploader" />
++-------------------------------+
+       
+       [[1]] Then use an UploadAttachment task:
+       
++-------------------------------+
+<bean parent="task.uploadAttachments">
+    <property name="attachmentUploader" ref="attachmentUploader" />
+    <property name="attachment">
+        <bean parent="taskArg.attachment">
+            <property name="name" value="myAttachment.txt" />
+        </bean>
+    </property>
+    <property name="resource" ref="basic.writeTo" />
+    <property name="attachTo">
+        <list>
+            <ref bean="basic.testResult" />
+        </list>
+    </property>
+</bean>
++-------------------------------+
+       
+       You have to specify an Attachment object with at least a 'name', you can also specify a 'contentType', but the server will recognize common extension of the name.
+       You have to specify a (Spring) Resource, for example the one that you created before (the name of the attachment doesn't have to be the name of the file).
+       Just doing this will already upload a file to the server, but if you want to access it you need to bind it to some object, typically a TreeTestResult. You can provide a list of AttachmentEnabled objects (only TreeTestResult implements it so far).
+       
+       You could use directly Spring Resource URL, e.g.:
+       
++-------------------------------+
+<property name="resource" value="osgibundle:/conf/main.xml" />
++-------------------------------+
+        
+       You can also upload and attach many attachments in one shot. In that case provide a Map with the keys being Attachment objects and the values Resource objects. E.g.:
+       
++-------------------------------+
+<bean parent="task.uploadAttachments">
+    <property name="attachmentUploader" ref="attachmentUploader" />
+    <property name="attachments">
+        <map>
+            <entry>
+                <key>
+                    <bean parent="taskArg.attachment">
+                        <property name="name" value="Reached.csv" />
+                    </bean>
+                </key>
+                <bean factory-bean="fileDiff.testData" factory-method="getReached"
+                    scope="execution">
+                    <aop:scoped-proxy />
+                </bean>
+            </entry>
+            <entry>
+                <key>
+                    <bean parent="taskArg.attachment">
+                        <property name="name" value="Expected.csv" />
+                    </bean>
+                </key>
+                <bean factory-bean="fileDiff.testData" factory-method="getExpected"
+                    scope="execution">
+                    <aop:scoped-proxy />
+                </bean>
+            </entry>
+        </map>
+    </property>
+    <property name="attachTo">
+        <list>
+            <ref bean="fileDiff.testResult" />
+        </list>
+    </property>
+</bean>
++-------------------------------+
+       
+       Retrieving the resources from this bean:
+       
++-------------------------------+
+<bean id="fileDiff.testData" parent="testData.reachedExpected"
+    scope="execution">
+    <aop:scoped-proxy />
+    <property name="expected" value="osgibundle:/inputs/csvdiff/@{fileName}.csv" />
+    <property name="reached"
+        value="osgibundle:/inputs/csvdiff/@{fileName}_mod.csv" />
+</bean>
++-------------------------------+
+       
+       [[1]] You can access the attachments from the Web UI by selecting a result in the list in the results perspective.
+       You will see that a new button 'Attachment' in the toolbar get activated (if there are any attachments).

diff --git a/src/site/apt/howtos/howto-executionResources.apt b/src/site/apt/howtos/howto-executionResources.apt
new file mode 100644 (file)
index 0000000..a73cd55
--- /dev/null
+++ b/src/site/apt/howtos/howto-executionResources.apt
@@ -0,0 +1,92 @@
+Management of writable files within tests
+
+       This provides an abstraction for files generated by the test.
+       
+       The files are stored in the standard osgi instance area (argument -data <my data area> to an OSGi launch, default is a ./data directory in the execution directory) under a ${osgi.instance.area}/executionResources directory.
+       
+       A subdirectory is created for each execution, thus avoiding that the files override each other.
+       
+       The format of this directory is yyyyMMdd_HHmmss_<execution context uuid>
+       
+       In order to use it:
+       
+       [[1]] First declare a ResourcesManager in your application context. It has to reference the SLC Execution Context (always available):
+           
++-------------------------------+
+<bean id="basic.resourcesManager" parent="slcTemplate.fileResources">
+    <property name="executionContext" ref="executionContext" />
+</bean>
++-------------------------------+
+       
+       [[1]] Then you can retrieve Spring Resources via a call to this manager. For example (it could also be an inner bean):
+       
++-------------------------------+
+<bean id="basic.writeTo" factory-bean="basic.resourcesManager"
+    factory-method="getWritableResource" scope="execution">
+    <constructor-arg value="subdir/writeTo" />
+    <aop:scoped-proxy />
+</bean>
++-------------------------------+
+       
+       The "constructor argument" (just a Spring notation in this case) is a relative path that you want to give to this file.
+       Within a given execution, repeated calls on the manager with the same relative path will always point to the same file.
+       
+       [[1]] Then simply use this standard Spring Resource where required:
+       
++-------------------------------+
+<bean parent="task.echo">
+    <property name="message" value="DATA" />
+    <property name="writeTo" ref="basic.writeTo" />
+</bean>
++-------------------------------+
+       
+       Underlying calls to the getFile() method of this resource won't fail (since they are writable).
+
+Factory bean for execution resources
+
+       Here is an enhancement to declare execution resources:
+       
++-------------------------------+
+<bean id="executionResources.placeholderPass" parent="slcTemplate.simpleFlow">
+    <constructor-arg ref="executionResources.spec" />
+    <property name="executables">
+        <list>
+            <bean parent="task.echo">
+                <property name="message" value="DATA" />
+                <property name="writeTo">
+                    <bean parent="slcTemplate.resourcesFactoryBean" scope="execution">
+                        <property name="executionResources" ref="executionResources" />
+                        <property name="relativePath" value="subdir/@{var}" />
+                        <aop:scoped-proxy />
+                    </bean>
+                </property>
+            </bean>
+        </list>
+    </property>
+</bean>
++-------------------------------+
+       
+       This allows to pass @{} execution parameters.
+       
+       The other form WON'T WORK if you try to passe @{} in the constructor-arg tag (but still works if the relative path does not contain a @{}):
+       
++-------------------------------+
+<bean id="executionResources.placeholderFail" parent="slcTemplate.simpleFlow">
+    <constructor-arg ref="executionResources.spec" />
+    <property name="executables">
+        <list>
+            <bean parent="task.echo">
+                <property name="message" value="DATA" />
+                <property name="writeTo">
+                    <bean factory-bean="executionResources" factory-method="getWritableResource"
+                        scope="execution">
+                        <constructor-arg value="subdir/@{var}" />
+                        <aop:scoped-proxy />
+                    </bean>
+                </property>
+            </bean>
+        </list>
+    </property>
+</bean>
++-------------------------------+
+       

diff --git a/src/site/site.xml b/src/site/site.xml
index 0443b01f52a6436340b2118a1742d654a1e54f26..88f8bcab3dccda89afa1c7f8030efb1398946673 100644 (file)
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -16,6 +16,12 @@
                                <item name="Unit Tests Results"
                                        href="${project.url}/surefire-report.html" />
                        </item>
                                <item name="Unit Tests Results"
                                        href="${project.url}/surefire-report.html" />
                        </item>

+                       <item name="How-To">
+                               <item name="Execution Resources"
+                                       href="${project.url}/howtos/howto-executionResources.html" />
+                               <item name="Attachments"
+                                       href="${project.url}/howtos/howto-attachments.html" />
+                       </item>

                        <item name="Argeo RIA (Web UI)"  href="${project.url}/server/org.argeo.slc.ria/index.html">
                                <item name="API"
                                        href="${project.url}/server/org.argeo.slc.ria/argeo-ria-api/index.html" />
                        <item name="Argeo RIA (Web UI)"  href="${project.url}/server/org.argeo.slc.ria/index.html">
                                <item name="API"
                                        href="${project.url}/server/org.argeo.slc.ria/argeo-ria-api/index.html" />