Example 3: Upload an archived complex content

In this case, the server accepts complex contents like an archived website. The server needs more metadata than in the previous cases. The process is composed of two steps, one optional interaction step which helps the user to deploy his website, and the required upload step.

Server manifest

1
<?xml version="1.0" encoding="UTF-8"?>
2
<cid:manifest xmlns:cid="http://www.cid-protocol/schema/v1/core" xmlns:xml="http://www.w3.org/XML/1998/namespace"
3
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
              xsi:schemaLocation="http://www.cid-protocol/schema/v1/core ../manifest/cid-core.xsd ">
5
    <cid:process is="http://schema.org/SendAction">
6
        <cid:label xml:lang="fr">Dépot de d'archives de ressources</cid:label>
7
        <cid:meta name="Folder-path">
8
            <cid:label xml:lang="en">Storage folder</cid:label>
9
            <cid:doc xml:lang="en">
10
                Path to the folder where the archive is unarchived.</cid:doc>
11
        </cid:meta>
12
        <!--
13
          The content-type metadata describes the type of the archive (and not of
14
          its content). In this description, the server furnishes three possible
15
          values. The client must select a value between them.
16
        -->
17
        <cid:meta name="Content-type" is="http://purl.org/dc/elements/1.1/type">
18
            <cid:label xml:lang="en">Available archived formats</cid:label>
19
            <cid:value>application/zip</cid:value>
20
            <cid:value>application/jar</cid:value>
21
            <cid:value>application/x-tar</cid:value>
22
        </cid:meta>
23
        <!--
24
          The names of the files compressed in a zip archive could be encoded
25
          following several schemes. In order to correctly decode it, this server
26
          request the encoding scheme as a metadata.
27
        -->
28
        <cid:meta name="Zip-file-names-encoding">
29
            <cid:label xml:lang="fr">File name encoding of the archive</cid:label>
30
            <cid:doc xml:lang="fr">This metadata should be sent if the Content-type is "application/zip".</cid:doc>
31
            <cid:value>UTF-8</cid:value>
32
            <cid:value>ISO-8859-1</cid:value>
33
            <cid:value>CP437</cid:value>
34
        </cid:meta>
35
        <!--
36
          This process is composed of two steps :
37
          
38
          1. An optional interaction step (which could use the Folder-path
39
          metadata). This interaction allows the user to define the path where
40
          the file will be unarchived. In this example, the Folder-path could be
41
          sent by the client in the request. The server could then build a
42
          dedicated GUI where this path is already selected. The server returns
43
          the overloaded Folder-path value in the "cid-interaction-ended" event.
44
45
          2. A required upload step, which needs the folder-path and the
46
          content-type metadata and which could use the Zip-file-names-encoding
47
          metadata.
48
        -->
49
        <cid:interact url="http://..." useMetas="Folder-path" returnMetas="Folder-path" required="false"/>
50
        <cid:upload url="http://..." needMetas="Zip-file-names-encoding Content-type Folder-path" required="true"/>
51
    </cid:process>
52
    <!--
53
      The web transport specified by this server includes a session property.
54
      This property could be returned whith the metadata at each step of the
55
      process. When this property is returned, the client must send it back in the
56
      next step of the process. This feature enables statefull servers.
57
    -->
58
    <cid:transports>
59
        <cid:webTransport sessionProperties="session-ID">
60
            <cid:authentications>
61
                <cid:basicHttp/>
62
                <cid:webAuthentication url="http://example.com/auth"/>
63
            </cid:authentications>
64
            <cid:webInteract>
65
                <cid:request method="GET" properties="header queryString"/>
66
                <cid:request method="POST;application/x-www-form-urlencoded" properties="queryString header post"/>
67
                <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
68
            </cid:webInteract>
69
            <cid:webUpload>
70
                <cid:request method="GET" properties="header queryString"/>
71
                <cid:request method="PUT" properties="header queryString"/>
72
                <cid:request method="POST" properties="queryString header"/>
73
                <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
74
            </cid:webUpload>
75
        </cid:webTransport>
76
    </cid:transports>
77
</cid:manifest>

The process step by step

Procedure

  1. Manifest exposition

    The server must expose the XML manifest to an accessible URL. For example, at http://example.com/manifest.xml.

  2. Download the manifest

    In order to understand the process, a client must download the server manifest and analyze it.

    Download the manifest
  3. Optional interaction

    Depending on the context, the client could be unable to furnish a valid Folder-path metadata. This interaction step allows the server to:

    • optionally get a Folder-path given by a client ;

    • interact directly with the user in order to overload this value;

    • return the overloaded value to the client in data part of the message event.

    Direct interaction

    In addition, the server could also return the defined session property (session-id) in the body of the custom event.

  4. Archive upload

    At this stage, the client should be able to send all the required properties either with or without interaction. The client must send the upload request following one of the defined upload transports.

    For example, it could send the content via an HTTP POST request, the archive in the body and the metadata as a query string (see rfc3986).

    Content upload