Move site definition to /doc

[gpl/argeo-slc.git] / doc / site / apt / howtos / howto-executionResources.apt

diff --git a/doc/site/apt/howtos/howto-executionResources.apt b/doc/site/apt/howtos/howto-executionResources.apt
new file mode 100644 (file)
index 0000000..a73cd55
--- /dev/null
+++ b/doc/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>
++-------------------------------+
+