From 6e587292f37379501e3b1b5f68fce6f46f3ea408 Mon Sep 17 00:00:00 2001
From: Erik Wilson <erik.wilson@rackspace.com>
Date: Thu, 22 Jan 2015 16:09:38 -0600
Subject: [PATCH] Adds scheduling objects for deletion info to End User Guide

With the moving of the Object Storage API content from a
long-form dev guide to a specification, some topics needed
To be added to the End User Guide.

Change-Id: I3a009139cc5d3b890fd12d4850e61b41401ee461
Partial-bug: 1392382
---
 doc/user-guide/ch_sdk.xml                     |  1 +
 .../large-object-upload-next-segment-req.txt  |  2 +-
 .../large-object-upload-segment-req.txt       |  2 +-
 .../section_object-api-expire-objects.xml     | 69 +++++++++++++++++++
 4 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 doc/user-guide/section_object-api-expire-objects.xml

diff --git a/doc/user-guide/ch_sdk.xml b/doc/user-guide/ch_sdk.xml
index f2821ab7c3..97202acb45 100644
--- a/doc/user-guide/ch_sdk.xml
+++ b/doc/user-guide/ch_sdk.xml
@@ -30,6 +30,7 @@
   <xi:include href="section_sdk_authenticate.xml"/>
   <xi:include href="section_sdk_manage_images.xml"/>
   <xi:include href="section_object-api-cors-headers.xml"/>
+  <xi:include href="section_object-api-expire-objects.xml"/>
   <xi:include href="section_sdk_configure_instances.xml"/>
   <xi:include href="section_sdk_neutron.xml"/>
   <xi:include href="section_sdk_nova.xml"/>
diff --git a/doc/user-guide/samples/large-object-upload-next-segment-req.txt b/doc/user-guide/samples/large-object-upload-next-segment-req.txt
index b0ec4575a6..da66393960 100644
--- a/doc/user-guide/samples/large-object-upload-next-segment-req.txt
+++ b/doc/user-guide/samples/large-object-upload-next-segment-req.txt
@@ -1,5 +1,5 @@
 PUT /{api_version}/{account}/{container}/{object} HTTP/1.1
-Host: storage.clouddrive.com
+Host: storage.example.com
 X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
 ETag: 8a964ee2a5e88be344f36c22562a6486
 Content-Length: 1
diff --git a/doc/user-guide/samples/large-object-upload-segment-req.txt b/doc/user-guide/samples/large-object-upload-segment-req.txt
index b0ec4575a6..da66393960 100644
--- a/doc/user-guide/samples/large-object-upload-segment-req.txt
+++ b/doc/user-guide/samples/large-object-upload-segment-req.txt
@@ -1,5 +1,5 @@
 PUT /{api_version}/{account}/{container}/{object} HTTP/1.1
-Host: storage.clouddrive.com
+Host: storage.example.com
 X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
 ETag: 8a964ee2a5e88be344f36c22562a6486
 Content-Length: 1
diff --git a/doc/user-guide/section_object-api-expire-objects.xml b/doc/user-guide/section_object-api-expire-objects.xml
new file mode 100644
index 0000000000..4bdce4c097
--- /dev/null
+++ b/doc/user-guide/section_object-api-expire-objects.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section [ <!ENTITY % openstack SYSTEM "../common/entities/openstack.ent"> %openstack; ]>
+<section xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="expire-objects">
+    <title>Schedule objects for deletion</title>
+    <para>Scheduling an object for deletion is helpful for managing
+        objects that you do not want to permanently store, such as log
+        files, recurring full backups of a dataset, or documents or
+        images that become outdated at a specified future time.</para>
+    <para>To schedule an object for deletion, include one of these
+        headers with the &PUT; or &POST; request on the object:</para>
+    <variablelist>
+        <varlistentry>
+            <term>X-Delete-At</term>
+            <listitem>
+                <para>A UNIX epoch timestamp, in integer form. For
+                    example, <literal>1348691905</literal> represents
+                        <literal>Wed, 26 Sept 2012 20:38:25
+                        GMT</literal>. Specifies the time when you
+                    want the object to expire, no longer be served,
+                    and be deleted completely from the object
+                    store.</para>
+            </listitem>
+        </varlistentry>
+        <varlistentry>
+            <term>X-Delete-After</term>
+            <listitem>
+                <para>An integer value. Specifies the number of
+                    seconds from the time of the request to when you
+                    want to delete the object.</para>
+                <para>This header is converted to an
+                        <literal>X-Delete-At</literal> header that is
+                    set to the sum of the
+                        <literal>X-Delete-After</literal> value plus
+                    the current time, in seconds.</para>
+            </listitem>
+        </varlistentry>
+    </variablelist>
+    <note>
+        <para>Use <link xlink:href="http://www.epochconverter.com/"
+                >http://www.epochconverter.com/</link> to convert
+            dates to and from epoch timestamps and for batch
+            conversions.</para>
+    </note>
+    <para>Use the &POST; method to assign expiration headers to
+        existing objects that you want to expire.</para>
+    <simplesect>
+        <title>Delete object at specified time request</title>
+        <para>In this example, the <literal>X-Delete-At</literal>
+            header is assigned a UNIX epoch timestamp in integer form
+            for <literal>Mon, 11 Jun 2012 15:38:25 GMT</literal>.</para>
+        <screen><prompt>$</prompt> <userinput>curl -i <replaceable>publicURL</replaceable>/marktwain/goodbye -X PUT -H "X-Auth-Token: <replaceable>token</replaceable>" \
+-H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H \
+"Content-Type: application/octet-stream"</userinput></screen>
+    </simplesect>
+    <simplesect>
+        <title>Delete object after specified interval request</title>
+        <para>In this example, the <code>X-Delete-After</code> header
+            is set to 864000 seconds. After this time, the object
+            expires.</para>
+        <screen><computeroutput>PUT /&lt;api version>/&lt;account>/&lt;container>/&lt;object> HTTP/1.1
+Host: storage.example.com
+X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
+Content-Type: image/jpeg
+X-Delete-After: 864000</computeroutput></screen>
+    </simplesect>
+</section>