<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<book xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
    <info>
        <title>DNet Object Store Module</title>
        <author>
            <orgname>ISTI CNR</orgname>
            <email>sandro.labruzzo@isti.cnr.it</email>
        </author>
    </info>
    <part>
        <title>ObjectStore API</title>
        
        <chapter>
            <title>Introduction</title>            
            <sect1>
                <title>What is an Object Store</title>                
                <para>Object Store Service is a DNet service that provides functions for perstistent
                    storage of files, and provides a REST API for fetching them back. </para>
                <para>It is composed by three different sub-modules:</para>
                <para>
                    <itemizedlist>
                        <listitem>
                            <para><link
                                    xlink:href="https://svn.driver.research-infrastructures.eu/driver/dnet11/modules/dnet-objectstore-rmi/trunk/"
                                    >dnet-objectstore -rmi</link>: it contains the interface of the
                                Object Store Service and includes some utility classes defining
                                metadata information for each file (i.e., ObjectStoreFile). These
                                metadata allow the Object Store Service to store and fetch the
                                associated files in a consistent way.</para>
                        </listitem>
                        <listitem>
                            <para><link
                                    xlink:href="https://svn.driver.research-infrastructures.eu/driver/dnet11/modules/dnet-modular-objectstore-service/trunk/"
                                    >dnet-modular-objectstore-service</link>: it contains the high
                                level implementation of the service. It manages blackboard messages,
                                the creation of profiles in dnet, and defines the REST API.</para>
                        </listitem>
                        <listitem>
                            <para><link
                                    xlink:href="https://svn.driver.research-infrastructures.eu/driver/dnet11/modules/dnet-gridfs-objectstore/trunks/"
                                    >dnet-gridfs-objectstore</link>: low level implementation for
                                storing and retreiving files using mongo GRIDFS. </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </sect1>
            <sect1>
                <title>The ObjectStoreFile Metadata</title>
                <para>To enable the object store to store a file, it is necessary give some
                    information about it such as:<itemizedlist>
                        <listitem>
                            <para>ObjectID (Required to identify the file)</para>
                        </listitem>
                        <listitem>
                            <para>Mime type</para>
                        </listitem>
                        <listitem>
                            <para>Access protocol (required). At the moment the only protocols
                                available are: http, ftp, file system.</para>
                        </listitem>
                        <listitem>
                            <para>URI (required)</para>
                        </listitem>
                        <listitem>
                            <para>username, password for connection (optional, if needed).</para>
                        </listitem>
                    </itemizedlist></para>
            </sect1>
        </chapter>
        <chapter>
            <title>Feeding Object Store</title>
            <sect1>
                <title></title>
                <para>Feeding Object Store Service can be done in two different ways:</para>
                <para><itemizedlist>
                        <listitem>
                            <para>Feed of a single file: performed by invoking the following web
                                service method
                                <programlisting>feedObject( String obsId, String objectMetadata)</programlisting>where
                                objectMetadata is a JSON serialization of an ObjectStoreFile
                                instance defined in the objectStore-RMI.</para>
                        </listitem>
                        <listitem>
                            <para>Feed of multiple files in bulk: performed via blackboard message
                                on the profile of the Object Store Service. The blackboard message
                                has to specify an EPR of ObjectStoreFile result set and the targeted
                                the ObjectstoreID.</para>
                        </listitem>
                    </itemizedlist> Please find two example of feeding techniques below.</para>
            </sect1>
            <sect1>
                <title>Feeding of single object</title>
                <para>The code below shows how to upload a single file into an objectStore</para>
                <para>
                    <programlisting>
 private void feedTest(ServiceLocator &lt;ObjectStoreService> ObjectStoreServicelocator,
			String objectStoreID) throws ObjectStoreServiceException {
		
        //Get a reference of the Service       
        ObjectStoreService obsService = ObjectStoreServicelocator.getService();
        
        //Create the FILE
		ObjectStoreFile metadataFile = new ObjectStoreFile();
		metadataFile.setObjectID("MyID");
		metadataFile.setMimeType("pdf");
		metadataFile.setURI("ftp://myURL/FTP");
		metadataFile.setAccessProtocol(Protocols.FTP);
		//Could be unnecessary
        metadataFile.setUsernameAuth("usr");
		metadataFile.setPasswordAuth("pwd");

        //Feed
		obsService.feedObject(objectStoreID, metadataFile.toJSON());
}                   </programlisting>
                    
                </para>
            </sect1>
            <sect1>
                <title>Feeding of multiple objects</title>
                <para>The feeding of multiple objects can be performed by the mechanism of
                    bloackboard messaging within the profile service of the objectStore. The code
                    Below shows an example of feeding inside an example BlackBoardJobNode belonging
                    to a workflow.
                    <programlisting>
                   protected void prepareJob(final BlackboardJob job, final NodeToken token) {

		                final String epr = token.getEnv().getAttribute("epr");
                        final String objectStoreID = token.getEnv().getAttribute("objectStoreID");
		                super.prepareJob(job, token);

		                job.setAction("FEED");

		                try {
			                job.getParameters().put("epr",new String(Base64.encodeBase64(epr.getBytes("US-ASCII")),
							"US-ASCII"));
		                    } 
                        catch (UnsupportedEncodingException e) {
			                throw new RuntimeException("ERROR " + e.getMessage());
		                    }
		                job.getParameters().put("obsID",objectStoreID);
	                    }
                </programlisting>
                </para>
            </sect1>
        </chapter>
        <chapter>
            <title>Delivery from Object Store</title>
            <sect1>
                <title/>
                <para>
                    <programlisting>    /**
	 * Returns ResultSet EPR for delivered ObjectStore records in a particular
	 * range date.
	 * &lt;p>
	 * Please check service implementations for details on the expected format
	 * of the records in the result set epr.
	 * &lt;/p>
	 * &lt;p>
	 * This method could be used for a bulk deliver of all objects in the store
	 * &lt;/p>
	 * 
	 * @param obsId
	 *            identifier of the ObjectStore
	 * @param from
	 *            the minimum date of the object
	 * @param until
	 *            the maximum date of the object
	 * @return a ResultSet EPR. Each element of the result set contains the
	 *         objIdentifier of a record and its URL for retrieve the
	 *         inputstream of the file.
	 * @throws ObjectStoreServiceException
	 *             the object store service exception
	 */
	@WebMethod(operationName = "deliverObjects", action = "deliverObjects")
	public W3CEndpointReference deliverObjects(
			@WebParam(name = "obsId") String obsId,
			@WebParam(name = "from") Double from,
			@WebParam(name = "until") Double until)
			throws ObjectStoreServiceException;

	/**
	 * Returns ResultSet EPR for delivered ObjectStore records.
	 * &lt;p>
	 * Please check service implementations for details on the expected format
	 * of the records in the result set epr.
	 * &lt;/p>
	 * 
	 * @param obsId
	 *            identifier of the ObjectStore
	 * @param eprId
	 *            id of a ResultSet EPR with the identifiers of the interesting
	 *            objects. Each element of the result set contains the
	 *            objIdentifier of a record
	 * @return a ResultSet EPR. Each element of the result set contains the
	 *         objIdentifier of a record and its URL for retrieve the
	 *         inputstream of the file.
	 * @throws ObjectStoreServiceException
	 *             the object store service exception
	 */
	@WebMethod(operationName = "deliverObjectsByIds", action = "deliverObjectsByIds")
	public W3CEndpointReference deliverObjectsByIds(
			@WebParam(name = "obsId") String obsId,
			@WebParam(name = "eprId") W3CEndpointReference eprId)
			throws ObjectStoreServiceException;

	/**
	 * Returns an URL to retrieve the ObjectStore record.
	 * 
	 * @param obsId
	 *            identifier of the ObjectStore
	 * @param objectId
	 *            the id of the object
	 * @return the URL for retrieve the record
	 * @throws ObjectStoreServiceException
	 *             the object store service exception
	 */
	@WebMethod(operationName = "deliverObject", action = "deliverObject")
	public String deliverRecord(@WebParam(name = "obsId") String obsId,
			@WebParam(name = "objectId") String objectId)
			throws ObjectStoreServiceException;</programlisting>
                </para>
                <para>The delivery of file can be done by a call of the ObjectStore Service method,
                    that allow the delivery  in three different ways:<itemizedlist>
                        <listitem>
                            <para>DeliverObjects stored in an interval of time (from-to) </para>
                        </listitem>
                        <listitem>
                            <para>DeliveryObjects by a List of IDs of Objects</para>
                        </listitem>
                        <listitem>
                            <para>DeliveryObject by the ID</para>
                        </listitem>
                    </itemizedlist></para>
            </sect1>
        </chapter>
    </part>
</book>
