Welcome (anonymous guest)
The DDS Memory Media Reference Guide

Memory Media

In this section the parameters for exchange with the memory media is described.

Since AGETOR V. 4.0 accessing a media is done using a defined Access Point through the AccessPointFilter. In the following the AP properties are described.

Access Point ID

com.agetor.dds.media.mem extends com.agetor.dds.media.base

URI Format (v 4.0)

mem:/(<session>)/<folder>/(<mask>)

Where <folder> denote a slash separated list of folders and <mask> denote the final part - i.e. the file name to access. If mask is absent the URI denote a path and must terminate with a slash (/). This latter form should be used with the list operation.

<session> is a unique id assigned to the temporary collection by the system. You should never use self-created id's here but only use this optional id in the case where you wish to refer to a temporary collection of a calling transformation. In this case you must transfer the session id as a parameter between the transformations in the LocalCall invocation. See the section on Accessing Callers Memory Collection below.

This AP support the operations; list, get, put and delete.

Description

The mem media is a pseudo media that allows for temporary storage during AGETOR transformations while exposing an interface identical to the abstraction used for other "real" media like the file system, FTP servers etc.

You may store files during a transformation at strategic points and then list and get them later. This may be useful if you wish to build a zip archive or send a mail with multiple attachments or perform other operations that require a set of files.

The mem media is only accessible during an AGETOR transformation and does not exist in the Document Distribution Service (DDS) as a persistent storage. I.e. its life span is the time of the transformation execution only and any file held in the mem media is discarded when the transformation ends.

Operation: list

See Using the List Operation on Media for an introduction to the generic semantics of the list operation.

Properties

Parameter name Type Description Default
uri<required:string>The URI denoting the directory from where the search is to be performedN.A.
mql<required:string>An MQL expression stating what files to get"" which is interpreted as e[.t];
glFrom<optional:int>The starting index of the matching result from which to return entities. First record has index 1.1
glTo<optional:int>The ending index of the matching result from which to return entities. -1 denotes no end (return all)100
glRecurse<optional:boolean>States if sub folder should be recursed to find matching filesfalse
glFlat<optional:boolean>States if the result should be flattened - i.e. the be one long list of result entities or a nested structured with entities in folders (only apply on recursion with glRecurse)false

The memory media allows listing of all current content across the memory collections of all transformations. To achieve this you use the literal uri-expression "mem://*":

<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter">
  <param name="access-point" value="com.agetor.dds.media.mem" />
  <param name="action" value="list" />
  <param name="mql" value="e[.t];" />
  <param name="uri" value="mem://*" />
</filter>

Supported Entity Properties (in MQL expressions)

Property name Type Description
@id<property:string>Name of file
@size<property:int>Size of file
@ts<property:long>Timestamp of file when added to collection
$<*><meta:string>Any additional name/value pair that may have been associated with a file

Example

This example shows how to list all files in the mem media folder temp and order these by their timestamp ascending.
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="List media by timestamp">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="list" />
			<param name="uri" value="mem://temp/" />
			<param name="mql" value="e[.t='f'] order @ts asc;" />
		</filter>

Operation: get

Properties

Parameter name Type Description Default
uri<required:string>The URI denoting the file to getN.A.

Example

		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Get file previously stored">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="get" />
			<param name="uri" value="mem://temp/INPUT-FILE" />
		</filter>

Operation: put

Description

Stores a file on the mem media collection.

Properties

Parameter name Type Description Default
uri<required:string>The URI denoting the file to putN.A.
_ _ meta_ _<name> <optional:*>Any meta property to assossiate with the file in the memory media. Could be content-type or "my-property" N.A.

Example

		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Save file">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="put" />
			<param name="uri" value="mem://temp/INPUT-FILE" />
			<param name="__meta__content-type" value="{content-type}" />
			<param name="__meta__original" value="true" />
		</filter>

Operation: del

Description

Removes a file from the mem media collection if an exact URI match exist. Otherwise the delete operation will remove all entries having the given URI as their prefix. Thus to remove all files in sub-folder folder1:
<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter" description="Delete all entries with this prefix" output="input">
  <param name="access-point" value="com.agetor.dds.media.mem" />
  <param name="action" value="del" />
  <param name="uri" value="mem://folder1" />
</filter>

To delete the complete locally scoped memory collection:

<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter" description="Delete all entries in local memory collection">
  <param name="access-point" value="com.agetor.dds.media.mem" />
  <param name="action" value="del" />
  <param name="uri" value="mem://" />
</filter>
Note that all files will automatically be removed when the current transformation ends

Properties

Parameter name Type Description Default
uri<required:string>The URI denoting the file to deleteN.A.

Example

	<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
		description="Delete file">
		<param name="access-point" value="com.agetor.dds.media.mem" />
		<param name="action" value="del" />
		<param name="uri" value="mem://temp/INPUT-FILE" />
	</filter>

For advanced processing you may need to clear the complete memory collection:

<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter" description="Delete all entries in local memory collection">
  <param name="access-point" value="com.agetor.dds.media.mem" />
  <param name="action" value="del" />
  <param name="uri" value="mem://" />
</filter>

Accessing Callers Memory Collection

Since the default memory collection is strictly local to transformation currently executing, the files added to a called transformation are not visible to the parent transformation and vice-versa. To remedy this in cases where we wish to delegate some collection build-up to a called transformation, it is possible to pass the session-id of the current collection to the called transformation that may use this session id as part of its URI to refer to the memory collection.

The caller must pass the id of its memory collection to the called transformation as a parameter using the build-in reference {context.sessionId}.

	<filter class="dk.bording.axt.flow.LocalCall" description="Call Transform">
		<param name="function" value="addFileToParentMemoryCollection" />
		<param name="sessid" value="{context.sessionId}" />
	</filter>

The callee must use the received parameter as the <session-id>> part of its URI references:

	<doc description="addFileToParentMemoryCollection" name="addFileToParentMemoryCollection">
		<key name="function" value="addFileToParentMemoryCollection" />
		<key name="sessid" value="*" />

                <!-- get some file from file system -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="">
			<param name="access-point" value="com.agetor.dds.media.file" />
			<param name="action" value="get" />
			<param name="uri" value="file:/c:/temp/sourcedir/backup/jpg/tu_banner.jpg" />
		</filter>
                <!-- add the file to the callers memory collection -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="put" />
			<param name="uri" value="mem:/{sessid}/folder/banner.jpg" />
			<param name="__meta__content-type" value="text/html" />
			<param name="__meta__Content-ID" value="&lt;image&gt;" />
		</filter>
	</doc>

Example: Adding files to mem media, copying one to a new name and retrieving the content list

Below is an example of how the mem media can be used to build up a collection of files that might be used at a later stage together. The example adds the input stream, then some files of inlined content, copies the input file by a succession of get-put operations and finally lists the content of the memory collection.

The input to the transformation is simply a content-type variable that only serves to illustrate how arbitrary meta data may be stored with file entries in the memory media.

	<doc description="Put files to file media and return a list of the content"
		name="ex_ap_mem_put_list">
		<documentation>This example shows how add files to the mem media and
			list them in order of addition.</documentation>

		<key name="function" value="ex_ap_mem_put_list" />
		<key name="content-type" value="*" />

		<!-- Store the input as an entry -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Save file">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="put" />
			<param name="uri" value="mem://temp/INPUT-FILE" />
			<param name="__meta__content-type" value="{content-type}" />
			<param name="__meta__original" value="true" />
		</filter>

		<!-- Store some text as an entry -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Save file">
			<input><![CDATA[This is the content file 1 in the mem media]]></input>
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="put" />
			<param name="uri" value="mem://temp/MY-FILE-1" />
			<param name="__meta__content-type" value="text/plain" />
		</filter>

		<!-- Store some more text as an entry -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Save file">
			<input><![CDATA[This is the content file 2 in the mem media]]></input>
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="put" />
			<param name="uri" value="mem://temp/MY-FILE-2" />
			<param name="__meta__content-type" value="text/plain" />
		</filter>

		<!-- Now retrieve the original input-->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Get file previously stored">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="get" />
			<param name="uri" value="mem://temp/INPUT-FILE" />
		</filter>

		<!-- Store the retrieved original input as a new entry -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Save file">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="put" />
			<param name="uri" value="mem://temp/INPUT-FILE-COPY" />
			<param name="__meta__content-type" value="{content-type}" />
		</filter>

		<!-- Store an image fetched on the Internet referred by a URL -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="Get internet file" input="http://www.agetor.com/images/agetor/puzzled11.png">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="put" />
			<param name="uri" value="mem://temp/puzzled11.png" />
		</filter>

		<!-- Finally list the content of the memory -->
		<filter class="dk.bording.axt.client.docdeliver.AccessPointFilter"
			description="List media by timestamp">
			<param name="access-point" value="com.agetor.dds.media.mem" />
			<param name="action" value="list" />
			<param name="uri" value="mem://temp/" />
			<param name="mql" value="e[.t='f'] order @ts asc;" />
		</filter>
	</doc>


The result of the above transformation would be

<entitylist:entities resultSize="5" from="1" to="-1">
    <e t="f" URI="mem:/1.1/temp/INPUT-FILE">
        <p n="size" t="o">26</p>
        <p n="ts" t="o">1274860052019</p>
        <p n="content-type" t="m">text/plain</p>
        <p n="original" t="m">true</p>
        <p n="id" t="o">INPUT-FILE</p>
    </e>
    <e t="f" URI="mem:/1.1/temp/MY-FILE-1">
        <p n="size" t="o">43</p>
        <p n="ts" t="o">1274860052034</p>
        <p n="content-type" t="m">text/plain</p>
        <p n="id" t="o">MY-FILE-1</p>
    </e>
    <e t="f" URI="mem:/1.1/temp/MY-FILE-2">
        <p n="size" t="o">43</p>
        <p n="ts" t="o">1274860052050</p>
        <p n="content-type" t="m">text/plain</p>
        <p n="id" t="o">MY-FILE-2</p>
    </e>
        <e t="f" URI="mem:/1.1/temp/INPUT-FILE-COPY">
        <p n="size" t="o">26</p>
        <p n="ts" t="o">1274860052159</p>
        <p n="content-type" t="m">text/plain</p>
        <p n="id" t="o">INPUT-FILE-COPY</p>
    </e>
    <e t="f" URI="mem:/1.1/temp/puzzled11.png">
        <p n="size" t="o">24708</p>
        <p n="ts" t="o">1274860052237</p>
        <p n="id" t="o">puzzled11.png</p>
    </e>
</entitylist:entities>

(Category Examples, Category Examples AccessPointFilter)

See also

Category AGETOR Access Points, Category DDS Media
© Bording Data A/S