Hitachi Content Platform

Developer’s Guide

Building Open Applications on the Hitachi Content

Platform using the HCP REST API

By HCP Engineering

Version 2.1 (Revision 27)

Table of Contents
1 Introduction .............................................................................................................................................................. 5

1.1 Summary .......................................................................................................................................................... 5

1.2 Intended Audience ............................................................................................................................................ 5

1.3 Required Materials ........................................................................................................................................... 5

1.4 Recommended Reading ................................................................................................................................... 5

2 Getting Started with REST ...................................................................................................................................... 6

2.1 Creating an Object ............................................................................................................................................ 7

2.1.1 Using a HCP Namespace .......................................................................................................................... 7

2.1.2 Interpreting Responses ........................................................................................................................... 11

2.2 Retrieving an Object ....................................................................................................................................... 11

2.2.1 Using a Namespace ................................................................................................................................ 11

2.2.2 Interpreting Responses ........................................................................................................................... 13

2.3 Deleting an Object .......................................................................................................................................... 15

2.3.1 Using a Namespace ................................................................................................................................ 15

2.3.2 Interpreting Responses ........................................................................................................................... 16

2.4 Working with Conditionals .............................................................................................................................. 16

2.4.1 Conditionals ............................................................................................................................................. 16

2.4.2 Available Headers ................................................................................................................................... 17

2.4.3 Put operation with condition .................................................................................................................... 18

2.5 Working with System Metadata ...................................................................................................................... 19

2.5.1 Available Properties ................................................................................................................................. 19

2.5.2 Overriding Defaults .................................................................................................................................. 19

2.5.3 Adjusting Values ...................................................................................................................................... 21

2.5.4 Interpreting Responses ........................................................................................................................... 23

2.6 Working with Custom Metadata ...................................................................................................................... 23

2.6.1 Valid Formats ........................................................................................................................................... 23

Page |2
 2.6.2 Creating Custom Metadata ...................................................................................................................... 23

2.6.3 Retrieving Custom Metadata ................................................................................................................... 25

2.6.4 Deleting Custom Metadata ...................................................................................................................... 26

3 Planning Your Application ..................................................................................................................................... 27

3.1 Addressing Objects......................................................................................................................................... 27

3.1.1 Load Balancing ........................................................................................................................................ 27

3.1.2 Fault Tolerance ........................................................................................................................................ 29

3.1.3 Disaster Recovery ................................................................................................................................... 29

3.2 Managing Objects ........................................................................................................................................... 30

3.2.1 Region Management ............................................................................................................................... 30

3.2.2 Directory Layout ...................................................................................................................................... 31

3.3 Protecting Objects .......................................................................................................................................... 32

3.3.1 Authenticity and Checksums ................................................................................................................... 32

3.3.2 Reliability ................................................................................................................................................. 33

3.4 Retaining Objects ........................................................................................................................................... 33

3.4.1 Retention ................................................................................................................................................. 33

3.4.2 Retention Classes ................................................................................................................................... 34

3.4.3 Compliance Modes .................................................................................................................................. 35

3.4.4 Legal Holds .............................................................................................................................................. 36

3.5 Securing Objects ............................................................................................................................................ 36

3.5.1 HTTPS ..................................................................................................................................................... 36

3.5.2 Access Control ......................................................................................................................................... 36

3.5.3 Data Encryption ....................................................................................................................................... 36

3.5.4 Data Shredding ........................................................................................................................................ 37

4 Advanced Topics ................................................................................................................................................... 38

4.1 Handling Errors ............................................................................................................................................... 38

4.1.1 Retrying Transactions .............................................................................................................................. 38

4.1.2 Dealing with Failed Writes ....................................................................................................................... 38

4.2 Performance Programming ............................................................................................................................ 38

Page |3
 4.2.1 Concurrent Access .................................................................................................................................. 38

4.2.2 Persistent Connections ............................................................................................................................ 39

4.3 Alternative I/O ................................................................................................................................................. 39

4.3.1 Chunked Transfers .................................................................................................................................. 39

4.3.2 Partial Content Transfers ......................................................................................................................... 39

4.4 Versioning ....................................................................................................................................................... 41

4.4.1 Creating Versions .................................................................................................................................... 41

4.4.2 Retrieving Versions ................................................................................................................................. 41

4.4.3 Deleting Versions .................................................................................................................................... 41

4.4.4 Listing Versions ....................................................................................................................................... 42

4.5 Retrieving Status Information ......................................................................................................................... 43

4.5.1 Getting Object Information ....................................................................................................................... 43

4.5.2 Listing Directory Contents ....................................................................................................................... 44

4.5.3 Getting HCP Namespace Information ..................................................................................................... 45

5 Conclusions ........................................................................................................................................................... 48

6 Appendix ................................................................................................................................................................ 49

6.1 Supporting Libraries ....................................................................................................................................... 49

6.1.1 Apache HTTP client ................................................................................................................................. 49

6.2 REST API Quick Reference............................................................................................................................ 49

6.2.1 Request Methods .................................................................................................................................... 49

6.2.2 Request Headers ..................................................................................................................................... 50

6.2.3 Response Codes ..................................................................................................................................... 51

6.2.4 Response Headers .................................................................................................................................. 52

6.2.5 Retention Syntax ..................................................................................................................................... 53

6.2.6 XML Documents ...................................................................................................................................... 54

Page |4
1 Introduction
1.1 Summary
Hitachi Content Platform (HCP) is a distributed storage system designed to support large, growing repositories of
fixed-content data. HCP stores objects that include both data and metadata. It distributes these objects across the
storage space but still presents them as files in a standard directory structure. HCP provides access to stored objects
through the HTTP protocol, as well as through an integrated search facility.

This document provides Hitachi solution consultants, partners, and integrators with a step-by-step guide on working
with the HCP REST API and is applicable to HCP version 3.0 or later

This document is intended to be a quick start guide and by no means an exhaustive resource on developing
against the HCP API. For comprehensive documentation please refer to the resources that have been included
with your installation of HCP.

1.2 Intended Audience

This document is intended for developers interested in integrating their applications with the HCP REST API.
You should be familiar with the Java programming language, and have a working knowledge of TCP/IP
networking. Familiarity with HCP features and functionality is also recommended.

1.3 Required Materials

To use the examples in this document, you’ll need a working Linux, OSX, or Windows development environment
with the following libraries installed on your system:

 Apache HTTP Client 4.x

For more details see Section 6.1: Supporting Libraries.

1.4 Recommended Reading

For more information on topics covered in this document, see

 Hitachi Content Platform: Administering HCP


 Hitachi Content Platform: Using a Namespace

 Hitachi Content Platform: HCP Management API Reference

 Hitachi Content Platform: HCP: Metadata Query API Reference

 HTTP/1.1 Protocol Specification (IETF RFC 2068)

 Apache HTTP Client 4.x User Guide
Page |5
2 Getting Started with REST
Let’s begin with some simple example programs. Our aim is to familiarize you with the basic methods of storing
and retrieving data on HCP. We want to quickly get you to the point where you can start writing useful applications.
Studying examples is usually the best way to start. If you’re already familiar with the HCP REST API, you can skip
this section and proceed directly to Section 3: Planning Your Application.

The examples in this section are written in the Java programming language and use Apache HTTP Client, an open
source HTTP library.

A helpful tool when using Apache HTTP Client for development is to enable wire and context logging. This is
strongly recommended to see the traffic passed to and from HCP. In order to enable logging add the following to
your JVM process arguments.

-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog

-Dorg.apache.commons.logging.simplelog.showdatetime=true

-Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG

-Dorg.apache.commons.logging.simplelog.log.org.apache.http.wire=ERROR

Page |6
2.1 Creating an Object

2.1.1 Using a HCP Namespace

Namespaces provide support for a layer of data separation, allowing several applications to safely and securely share
the same tenant. It’s important to note that only authenticated users can access an HCP namespace unless
anonymous access is enabled. Also please note that these examples use HTTP which must be enabled on the
namespace

Let's get started. Our first program uploads content from the file hello.txt to an HCP repository. This file is a ASCII
file with the following text:

Hello world!

Welcome to the Hitachi content platform!

We’ll “PUT” our new object in the path “examples/world.txt” in the tenant called “tn01” with a namespace “ns01”.
Because this HCP namespace requires authentication, you will also need to present security credentials with each
HTTP request. Below is the code used in this example:

Page |7
 1 package com.hds;
2
3 import java.io.*;
4 import java.util.ArrayList;
5 import java.util.List;
6
7 import org.apache.http.client.entity.UrlEncodedFormEntity;
8 import org.apache.http.client.HttpClient;
9 import org.apache.http.client.methods.HttpDelete;
10 import org.apache.http.client.methods.HttpGet;
11 import org.apache.http.client.methods.HttpPost;
12 import org.apache.http.client.methods.HttpPut;
13 import org.apache.http.entity.ByteArrayEntity;
14 import org.apache.http.HttpResponse;
15 import org.apache.http.impl.client.HttpClientBuilder;
16 import org.apache.http.message.BasicNameValuePair;
17 import org.apache.http.NameValuePair;
18
19 public static void put() throws IOException{
20 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
21 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt";
22
23 //specify path to file you want to upload(PUT)
24 String localFilePath = "/Users/japark/Development/Java/HCPJavaRestSamples/world.txt";
25
26 //create a new HttpClient object and a PUT request object
27 HttpClient client = HttpClientBuilder.create().build();
28 HttpPut request = new HttpPut(url);
29
30 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
31 request.addHeader("Authorization", "HCP
32 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
33
34 //setup byte array for file to upload(PUT)
35 File input = new File(localFilePath);
36 byte[] fileAsByteArr = Utils.fileToByteArray(input);
37
38 ByteArrayEntity requestEntity = new ByteArrayEntity(fileAsByteArr);
39
40 //set the request to use the byte array
41 request.setEntity(requestEntity);
42 //execute PUT request
43 HttpResponse response = client.execute(request);
44
45 //print response status to console
46 System.out.println("Response Code : "
47 + response.getStatusLine().getStatusCode() + " " +
48 response.getStatusLine().getReasonPhrase());
49
50 }

Page |8
When you run this program, the output from your machine should look something like this

Response Code : 201 Created

First lets direct your attention to the URL you used from your namespace program. In order to perform an operation
against HCP’s REST API you will always need to specify a “resource” by supplying a URL. In this example you can
see that we are using the “ns01” namespace located within the “tn01” tenant which is on the HCP system located
at “hcp01.hitachi.com”. In addition we can see that we are using the “REST” interface and addressing the path
“examples/world.txt”. See below for a visual representation of the URL anatomy.

Next, lets direct your attention to how we authenticated against HCP. HCP supports a number of different
authentications options such as Active Directory pass through, SPNEGO, and local authentication. In this example
we authenticated ourselves using a local account with the user “exampleuser” with a password of “passw0rd”. In
order to pass this information to HCP we generated an “Authorization” header with the value of “HCP
ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb”. Please note that we have taken the Base64 value of
the username, and the md5 hash of the password and concatinated the two values placing the colon character
between them. We have also prepended “HCP” to the generated values.

Let’s build a sample authorization token, step by step.

acct username exampleuser

acct password passw0rd

base64(exampleuser) ZXhhbXBsZXVzZXI=
md5(passw0rd) bed128365216c019988915ed3add75fb

calculated token HCP ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb

HCP uses the Host header to determine which namespace you are writing to. Apache automatically populates the
Host header, extracting the information from the URL you provide.

Page |9
 WARNING!

If you are not using a library to handle HTTP for you, be sure to transmit
a properly formatted Host header with your request. HCP will reject your
transaction otherwise.

WARNING!

If you are using IP addresses in your URL, be sure to transmit a properly

formatted Host header – complete with namespace and tenant information
– with your request. HCP will reject your transaction otherwise.

Object data is attached to the body of a PUT request. Apache provides built-in functions to read data from a
byte array for upload.

33 //setup.byte.array.for.file.to.upload(PUT)
34 File.input = new File(loaclFilePath):
35 byte[] fileAsByteArr = Utils.fileToByteArray(input);
36
37 ByteArrayEntity.requestEntity = new ByteArryEntity(fileAsByteArr);
38
39 //set the request to us the byte array
40 request.setEntity(requestEntity);

P a g e | 10
2.1.2 Interpreting Responses
HCP uses standard HTTP/1.1 response codes to communicate transaction status. HCP error responses will not
provide great detail in to the underlying cause for security purposes. A 403 code for example could mean bad
credentials, a namespace or tenant does not exist, or that a user does not have the required permissions.

That being said, common return values for PUT requests include

Status Summary Description

201 Created Success

403 Forbidden Protocol disabled, or

Insufficient permissions

409 Conflict Object already exists

413 File Too Large Insufficient capacity

Apache maps HTTP responses to.specific error codes by default. For instance, the response

HTTP/1.1 201 Created

is parsed by Apache and presented as the return value

HttpStatus.SC_CREATED

For more recommendations on proper error handling, see Section 4.1: Handling Errors.

HCP returns additional processing details in the header block. Let’s interpret the HTTP response to our program.

X-HCP-Hash: SHA-256 1E73F5BC665F518B5841507C451EC8FDDB5BD073113B66B640AC2F41F2036B58

ETag: "f363f9556891bd306aedd590b4d23a1e"

The X-HCP-HASH header is a checksum for data being sent to HCP for the hash algorithm specified for the
namespace. The ETAG header is an md5 checksum for the data sent to HCP. When a request arrives the repository
calculates a checksum for the object data received, which it returns as part of the HTTP response. The checksum
can be used by applications to ensure that data uploaded by the PUT request wasn't corrupted in-transit. Sample
code to authenticate content is included in Section 3.3.1: Authenticity and Checksums.

2.2 Retrieving an Object

2.2.1 Using a Namespace

In the last section we used the HCP REST API to upload content to a repository. In this one we’ll learn how to retrieve
it. The next program requests the object with path examples/world.txt from the namespace, and prints the content locally
to the console.

P a g e | 11
 1 public static void get() throws IOException{
2 //specify namespace URL - eg. ns01.tn01.hcp01.HCP.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt";
4
5 //create a new HttpClient object and a GET request object
6 HttpClient client = HttpClientBuilder.create().build();
7 HttpGet request = new HttpGet(url);
8
9 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
10 request.addHeader("Authorization", "HCP
11 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
12
13 //execute the request
14 HttpResponse response = client.execute(request);
15
16 //print response status to console
17 System.out.println("Response Code : "
18 + response.getStatusLine().getStatusCode() + " " +
19 response.getStatusLine().getReasonPhrase());
20
21 //get response content
22 BufferedReader rd = new BufferedReader(
23 new InputStreamReader(response.getEntity().getContent()));
24
25 //print response content to console
26 StringBuffer result = new StringBuffer();
27 String line = "";
28 while ((line = rd.readLine()) != null) {
29 result.append(line);
30 }
31 System.out.println(result.toString());
32 }

P a g e | 12
When you run this program, the HTTP request from your machine should look something like this:

Response Code : 200 OK

Hello World! Welcome to the Hitachi Content Platform!

The GET method is used to retrieve existing objects. You can instruct Apache to issue an HTTP GET request by
creating an HttpGet object.

Lets take a look at the URL we used to GET the object data. You should notice that the URL used is the same as when
we PUT the object into the namespace. A visual representation of the anatomy of a GET request is below.

2.2.2 Interpreting Responses

HCP uses standard HTTP/1.1 response codes to communicate transaction status. Common return values for
GET requests include

Status Summary Description

200 OK Success

404 Not found Object does not exist

503 Service Unavailable Try again

HCP also returns additional processing details in the header block.

X-HCP-Time: 1259584200
Content-Type: text/plain
Content-Length: 12
X-HCP-Type: object
X-HCP-Size: 12
X-HCP-Hash: SHA-256 D2A84F4B8B6...
X-HCP-VersionId: 80205544854849
X-HCP-IngestTime: 1258469614
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: false

P a g e | 13
 X-HCP-Custom-Metadata: false

For a list of commonly encountered headers and their function, see Section 6.3.4.1: Authenticated Namespaces. For
a full description of HCP response headers, see Hitachi Content Platform: Using a Namespace.

Object data is attached to the body of a GET response. Apache provides built-in functions that allow you to grab the
data to write to disk. In the following code we write the content to “/tmp/outfile.txt”. Please note that we are using a
BufferedInputStream for faster performance.

1 BufferedInputStream bis = new BufferedInputStream(entity.getContent());

2 String filePath = /tmp/outfile.txt""
3 BufferedOutputStream bos = new BufferedOutputStream(new FileOutputStream(new
4 File(filePath)));
5 int inByte;
6 while((inByte = bis.read()) != -1) bos.write(inByte);
7 bis.close();
8 bos.close();
9 }

P a g e | 14
 2.3 Deleting an Object
2.3.1 Using a Namespace
The REST API can be used to delete objects from a repository. The next program deletes the object
examples/world.txt from the namespace.

1 public static void delete() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?" +
4
5 //create a new HttpClient object and a DELETE request object
6 HttpClient client = HttpClientBuilder.create().build();
7 HttpDelete request = new HttpDelete(url);
8
9 // add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
10 request.addHeader("Authorization", "HCP
11 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
12
13 //execute DELETE request
14 HttpResponse response = client.execute(request);
15
16 //print response status to console
17 System.out.println("Response Code : "
18 + response.getStatusLine().getStatusCode() + " " +
19 response.getStatusLine().getReasonPhrase());
20 }

P a g e | 15
When you run this program, the HTTP request from your machine should look something like this:

Response Code : 200 OK

The DELETE method is used to delete objects. You can instruct Apache to issue an HTTP DELETE request
by creating an HttpDelete object.

2.3.2 Interpreting Responses

HCP uses standard HTTP/1.1 response codes to communicate transaction status. Common return values for
GET requests include

Status Summary Description

200 OK Success

403 Forbidden Object under retention

Access method (HTTP or HTTPS) is disabled.

404 Not Found Object not found

Objects under retention or on legal hold cannot be deleted by normal means. See Section 3.4: Retaining Objects for
more details.

2.4 Working with Conditionals

2.4.1 Conditionals
HCP allows for conditional operations when making a request. In doing so you can greatly optimize the number of
operations used against HCP. For example, a user might choose to only want download a file if HCP has a different
version of the file than what is stored locally. In making the operation conditional, we can save both the time
required for a response to finish, as well as require fewer operations to be used in general.

P a g e | 16
2.4.2 Available Headers

Header Values Description

One of:
• Comma-separated list of Execute If-Match provided
If-Match
ETag values etag value
• asterisk
(*) One of:
• Comma-separated list of Execute If- None-Match
If-None-Match
ETag values provided etag value
• asterisk (*)
Execute If Modified since
If-Modified-Since Datetime value
provided date
If-Unmodified- Execute if unmodified since
Datetime value
Since provided date
One of:
• Comma-separated list of Execute If-Match provided
X-HCP-CopySource-If-Match
ETag values etag value
• asterisk (*)
One of:
• Comma-separated list of Execute If- None-Match
X-HCP-CopySource-If-None-Match
ETag values provided etag value
• asterisk (*)
X-HCP-CopySource-If-Modified- Execute If Modified since
Datetime value
Since provided date
If-Unmodified-
Execute if unmodified since
X-HCP-CopySource-If-Unmodified- Datetime value
provided date
Since

P a g e | 17
 2.4.3 Put operation with condition

Let’s update our program from Section 2.1.1 to only PUT an object if the current version of the object matches the
md5 hash given.

1 public static void put() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt";
4
5 //specify path to file you want to upload(PUT)
6 String localFilePath = "/Users/japark/Development/Java/HCPJavaRestSamples/world.txt";
7
8 //create a new HttpClient object and a PUT request object
9 HttpClient client = HttpClientBuilder.create().build();
10 HttpPut request = new HttpPut(url);
11
12 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
13 request.addHeader("Authorization", "HCP ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
14 request.addHeader("If-None-Match", "86d434bcb3a1af9b0b764fc7dd4dd31a");
15 request.addHeader("Expect", "100-CONTINUE");
16
17 //setup byte array for file to upload(PUT)
18 File input = new File(localFilePath);
19 byte[] fileAsByteArr = Utils.fileToByteArray(input);
20
21 ByteArrayEntity requestEntity = new ByteArrayEntity(fileAsByteArr);
22
23 //set the request to use the byte array
24 request.setEntity(requestEntity);
25 //execute PUT request
26 HttpResponse response = client.execute(request);
27
28 //print response status to console
29 System.out.println("Response Code : "
30 + response.getStatusLine().getStatusCode() + " " + response.getStatusLine().getReasonPhrase());
31
32 }

P a g e | 18
 In the above example, HCP will evaluate the current version of the file world.txt and compare it with the hash
we provided as a header in line 14. If the current version does not match hash, you should see the following.

Response Code : 201 Created

Note that in the above code, we added the “If-None-Match” header as well as the “Expect” header. This tells Apache
to only send the body of the request if a “100-Continue” response is received. Apache will handle the interim steps for
you.

2.5 Working with System Metadata

2.5.1 Available Properties

HCP objects have three major components: object data, system metadata, and custom metadata. System metadata
is used to define object behavior. There are four types of system metadata which can be manipulated by the HCP
REST interface:

Property Values Description

hold true, false Place or remove an object on legal hold

retention Any valid retention expression as Specify retention settings for an object.
defined in Section 3.4: Retaining
Objects

shred true, false Flag an object to be shredded following

deletion.

index true, false Flag an object to be indexed (if search is

supported)

This section teaches you how to manipulate system metadata. To better understand how HCP uses system
metadata to manage the retention of objects, see Section 3.4: Retaining Objects.

2.5.2 Overriding Defaults

New objects inherit system metadata from their namespace. You can override namespace defaults when creating an
object. Let’s modify the program from Section 2.1.1 to enable Indexing and Shredding on the object examples/world.txt
being created in namespace ns01.

1 public static void putWithIndexAndShreddingEnabled() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt" +
4 "?index=true&shred=true";
5
6 //specify path to file you want to upload(PUT)
7 String localFilePath = "/Users/japark/Development/Java/HCPJavaRestSamples/world.txt";
8
9 //create a new HttpClient object and a PUT request object
10 HttpClient client = HttpClientBuilder.create().build();
11 HttpPut request = new HttpPut(url);

P a g e | 19
12
13 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
14 request.addHeader("Authorization", "HCP ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
15
16 //setup byte array for file to upload(PUT)
17 File input = new File(localFilePath);
18 byte[] fileAsByteArr = Utils.fileToByteArray(input);
19
20 ByteArrayEntity requestEntity = new ByteArrayEntity(fileAsByteArr);
21
22 //set the request to use the byte array
23 request.setEntity(requestEntity);
24 //execute PUT request
25 HttpResponse response = client.execute(request);
26
27 //print response status to console
28 System.out.println("Response Code : "
29 + response.getStatusLine().getStatusCode() + " " + response.getStatusLine().getReasonPhrase());
30 }
31

P a g e | 20
 Overrides are specified by name as URL query parameters.

Any combination of ampersand-delimited properties can be included in the PUT request. As always, make sure your
data access account has sufficient privileges to create objects and set metadata, especially when enabling privileged
features like indexing and legal holds.

2.5.3 Adjusting Values

You can also modify the system metadata of an existing object. Let’s write a program to place a legal hold on the
object examples/world.txt in namespace ns01. Please note that we are executing a POST request by creating a new
HttpPost object.

1 public static void post() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt";
4
5 //create a new HttpClient object and a DELETE request object
6 HttpClient client = HttpClientBuilder.create().build();
7 HttpPost request = new HttpPost(url);
8
9 // add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
10 request.addHeader("Authorization", "HCP
11 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
12
13 // set field hold to true
14 List <NameValuePair> nameValuePairs = new ArrayList <NameValuePair>();
15 nameValuePairs.add(new BasicNameValuePair("hold", "true"));
16 request.setEntity(new UrlEncodedFormEntity(nameValuePairs));
17
18 //execute DELETE request
19 HttpResponse response = client.execute(request);
20
21 //print response status to console
22 System.out.println("Response Code : "
23 + response.getStatusLine().getStatusCode() + " " +
24 response.getStatusLine().getReasonPhrase());
25 }
26

P a g e | 21
 When you run this program, the HTTP request from your machine should look like this:

Response Code : 200 OK

Objects are addressed using the standard URL formats for HCP namespaces.

System metadata is included in the body as form-encoded data. Use the name value pairs to format and attach form-
encoded data to an HTTP transaction.

12 // set field hold to true

13 List <NameValuePair> nameValuePairs = new ArrayList <NameValuePair>();
14 nameValuePairs.add(new BasicNameValuePair("hold", "true"));
15 request.setEntity(new UrlEncodedFormEntity(nameValuePairs));

P a g e | 22
2.5.4 Interpreting Responses
HCP uses standard HTTP/1.1 response codes to communicate transaction status. Common return values for
POST requests include:

Status Summary Description

200 OK Metadata Updated Successfully

400 Bad Request The request is trying to change the retention setting from a
retention class to an explicit setting, such as an absolute Epochal
date.

The request is trying to change the retention setting and the

retention hold setting at the same time.

The request is trying to set a retention value for an object on hold.

The request is trying to set the shred value from true to false.

The URL in the request is not well-formed.

The request contains an unsupported parameter or an invalid

value for a parameter.

404 Not Found HCP could not find the specified object

2.6 Working with Custom Metadata

2.6.1 Valid Formats

Custom metadata is user- or application-specified data which can be attached to an object. All of the custom
metadata associated with an object must be represented as a single, well-formed XML document.

2.6.2 Creating Custom Metadata

Let’s learn how to bind custom metadata to an object. The next program attaches the contents of the file
myannotation.xml as custom metadata to the object examples/world.txt in the namespace Ns01.

P a g e | 23
1 public static void addMetaData() throws IOException{
2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?" +
4 "type=custom-metadata&annotation=myannotation";
5
6 //specify path to file you want to upload(PUT)
7 String localFilePath =
8 "/Users/japark/Development/Java/HCPJavaRestSamples/myannotation.xml";
9
10 //create a new HttpClient object and a PUT request object
11 HttpClient client = HttpClientBuilder.create().build();
12 HttpPut request = new HttpPut(url);
13
14 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
15 request.addHeader("Authorization", "HCP
16 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
17
18 //setup byte array for file to upload(PUT)
19 File input = new File(localFilePath);
20 byte[] fileAsByteArr = Utils.fileToByteArray(input);
21
22 ByteArrayEntity requestEntity = new ByteArrayEntity(fileAsByteArr);
23
24 //set the request to use the byte array
25 request.setEntity(requestEntity);
26 //execute PUT request
27 HttpResponse response = client.execute(request);
28
29 //print response status to console
30 System.out.println("Response Code : "
31 + response.getStatusLine().getStatusCode() + " " +
32 response.getStatusLine().getReasonPhrase());
33 }

P a g e | 24
 The well-formed XML file we are uploading contains the following content.

When you run this program, the HTTP request from your machine should look like this:

<?xml version=”1.0”?>
<world-params>
<cruelness unit=”skovels”>6371</cruelness>
<favorite-color>
<blue/>
<yellow/>
</favorite-color>
</world-params>

The PUT method is used to attach custom metadata to an object. Assigning the URL parameter type to a value of
custom-metadata identifies uploaded content as custom metadata. Please also note that we have also added the annotation
parameter with a value of my-annotation. HCP allows for up to ten annotations to be attached as custom metadata to each
object stored. If the annotation is well-formed XML it can be up to 1 MB in size. HCP will also accept any other file type with
a maximum size of 1 GB.

2.6.3 Retrieving Custom Metadata

Retrieving custom metadata is similar to retrieving object data. Let’s write a method to return custom metadata
from the object examples/world.txt in the namespace ns01.

1 public static void getMetaData() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?" +
4 "type=custom-metadata&annotation=myannotation";
5
6 //create a new HttpClient object and a GET request object
7 HttpClient client = HttpClientBuilder.create().build();
8 HttpGet request = new HttpGet(url);
9
10 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
11 request.addHeader("Authorization", "HCP
12 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
13
14 //execute the request
15 HttpResponse response = client.execute(request);
16
17 //print response status to console
18 System.out.println("Response Code : "
19 + response.getStatusLine().getStatusCode() + " " +
20 response.getStatusLine().getReasonPhrase());
21
22 //get response content
23 BufferedReader rd = new BufferedReader(
24 new InputStreamReader(response.getEntity().getContent()));
25
26 //print response content to console
27 StringBuffer result = new StringBuffer();
28 String line = "";
29 while ((line = rd.readLine()) != null) {
30 result.append(line);
31 }
32 System.out.println(result.toString());
33 }

P a g e | 25
 The GET method is used to retrieve custom metadata from an of object. Assigning the URL parameter type to a value
custom-metadata indicates that custom metadata should be we have returned in the response body. Please also note that
also added the annotation parameter with a value of my-annotation.

2.6.4 Deleting Custom Metadata

Deleting custom metadata is similar to deleting object data. Let’s modify the program in Section 2.2.1 to delete
custom metadata from the object examples/world.txt in the namespace ns01. The DELETE method is used to delete
custom metadata from an object. Assigning the URL parameter type to a value of custom-metadata indicates that only
custom metadata should deleted from the object. Please also note that we have also added the annotation parameter
with a value of my-annotation.

1 public static void delete() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?" +
4 "type=custom-metadata&annotation=myannotation”;";
5
6 //create a new HttpClient object and a DELETE request object
7 HttpClient client = HttpClientBuilder.create().build();
8 HttpDelete request = new HttpDelete(url);
9
10 // add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
11 request.addHeader("Authorization", "HCP ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
12
13 //execute DELETE request
14 HttpResponse response = client.execute(request);
15
16 //print response status to console
17 System.out.println("Response Code : "
18 + response.getStatusLine().getStatusCode() + " " + response.getStatusLine().getReasonPhrase());
19 }

P a g e | 26
3 Planning Your Application
By now you should have a basic understanding of how to work with a repository using the HCP REST API. In this
section, we examine some best practices to follow when building fault-tolerant, production-ready applications.

3.1 Addressing Objects

Applications connect to storage nodes over HTTP either by IP address or by DNS hostname. You are
strongly encouraged to use DNS hostnames when addressing an HCP system.

HCP periodically updates DNS records to reflect which storage nodes are up, running, and actively accepting traffic.
Here’s an example query for the IP address of the hostname www.hcp01.hitachi.com.

$ dig www.hcp01.hitachi.com
; <<>> DiG 9.6.1-P2 <<>> www.hcp01.hitachi.com ;;
global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 20452
;; flags: qr rd ra; QUERY: 1, ANSWER: 8, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;www.hcp01.hitachi.com. IN A
;; ANSWER SECTION:
www.hcp01.hitachi.com. 15 IN A 172.20.2.74
www.hcp01.hitachi.com. 15 IN A 172.20.2.75
www.hcp01.hitachi.com. 15 IN A 172.20.2.76
www.hcp01.hitachi.com. 15 IN A 172.20.2.77
www.hcp01.hitachi.com. 15 IN A 172.20.2.78
www.hcp01.hitachi.com. 15 IN A 172.20.2.79
www.hcp01.hitachi.com. 15 IN A 172.20.2.80
www.hcp01.hitachi.com. 15 IN A 172.20.2.81

As you can see, the HCP system is accessible from eight storage nodes. If a storage node becomes
unavailable, HCP will remove its IP address from the DNS record for www.hcp01.hitachi.com.

You can leverage this behavior to

 load balance traffic amongst storage nodes,


 provide fault tolerance in the event of storage node failures, and

 build disaster-recovery functionality into mission-critical applications

3.1.1 Load Balancing

Storage nodes in an HCP system run the same software stack. Administrators do not have to physically assign
roles and responsibilities. Storage nodes advertise a similar set of services to the outside world, and are largely
indistinguishable from one another. Contacting one is as good as contacting another. This behavior is common in
modern, web-based architectures, and lends itself well to industry-standard load balancing techniques.

HCP uses a load balancing technique called client-side round-robin DNS. Addressing a repository by its qualified
hostname will automatically distribute load amongst available storage nodes. Let’s take a look at an illustration of
the process.

P a g e | 27
Applications are given a different answer each time they query DNS for the hostname www.hcp01.hitachi.com.
Successive queries resolve to different IP addresses. HCP shuffles the authoritative answer list for each DNS
request it receives. This behavior distributes application traffic across the system, spreading load equally across the
storage nodes.

By contrast, directly addressing the system by IP address will result in your application contacting the same storage
node for every request it issues. This can lead to performance bottlenecks and creates a single point of failure in the
overall solution.

WARNING!

Make sure that both your operating system and runtime environment are
not caching DNS results. Your application will communicate with the
same storage node while its IP address remains in-cache. This may result
in performance bottlenecks.

HCP also works with commercial load balancing appliances. Contact a Hitachi Solutions Consultant for more
information on integrating HCP with hardware load balancing equipment.

P a g e | 28
3.1.2 Fault Tolerance
HCP is a distributed object store capable of reliably operating with multiple component failures. Applications, however,
need to know when a storage node is no longer available. Sending HTTP requests to an unresponsive IP address will
cause application errors, retry delays, and performance outages.

HCP regularly monitors components for failure and periodically updates DNS records to reflect their availability.
Addressing the system by its qualified hostname will automatically re-direct you away from unresponsive storage
nodes. Once a failure is detected, HCP will remove the offending IP address from the DNS answer list and divert
new HTTP transactions away from the misbehaving component.

You remain open to the risk of connecting to unresponsive storage nodes in the time window between a fault’s
occurrence and its detection. Applications should follow best practices detailed in Section 4.1: Handling Errors
to properly handle runtime errors and minimize their impact.

3.1.3 Disaster Recovery

For applications with high availability and reliability needs, HCP supports tenant-level replication of data to other HCP
systems. Let’s assume hitachi.com has stringent disaster recovery requirements, and has deployed two HCP systems
– each in its own datacenter – to provide failover services for one another. Data managed by the pacs tenant is
considered high-value and is actively being replicated from hcp01 to hcp02.

Applications typically read and write data from the primary, and use the secondary for disaster recovery and/or
load balancing purposes.

If the event of a serious service outage at Datacenter A or issues with hcp01, application servers in both datacenters
will need to direct traffic to the failover site.

From an application perspective, the URLs

P a g e | 29
 http://ct.pacs.hcp01.hitachi.com/rest/P293/S321/c7.dcm
http://ct.pacs.hcp02.hitachi.com/rest/P293/S321/c7.dcm

refer to the same object on the primary and backup systems, respectively. Applications can affect a passive
service failover by modifying the hostname in the object URL. Storing the primary and backup system hostnames
in a configuration file and building URLs to access objects at runtime is strongly recommended.

You should carefully consider how your application stores and assembles object URLs. Independently
managing HCP hostnames and object paths can help you build fault-tolerant, replication-friendly applications.

As of HCP version 7, active-active replication is supported. This allows for read and write operations to occur against
either one of our HCP systems in our example. In such cases, HCP will hyper replicate metadata from one system to
another and then replicate object data. In this failover situation writes can still occur against the system you’ve failed
over to.

3.2 Managing Objects

3.2.1 Region Management

HCP maintains a distributed database to track the placement and behavior of objects under management. Objects
are grouped into management sets known as regions. Each storage node is assigned a collection of regions to
maintain.

Objects are assigned to regions by their directory path. For instance, the objects

http://ns01.tn01.hcp01.hitachi.com/rest/examples/disco/earth.jpg
http://ns01.tn01.hcp01.hitachi.com/rest/examples/disco/wind.jpg
http://ns01.tn01.hcp01.hitachi.com/rest/examples/disco/fire.jpg

belong to the same region because they share the path /examples/disco. The objects

http://ns01.tn01.hcp01.hitachi.com/rest/examples/disco/earth.jpg
http://ns01.tn01.hcp01.hitachi.com/rest/examples/songs/september.mp3

belong to different regions, despite having a common directory prefix of /examples.

Creating an object requires updates to its corresponding region database to record system metadata. This
includes information like data placement and retention properties. HCP uses region databases to physically locate
objects amongst the large number of disks, LUNs, and storage nodes under management.

P a g e | 30
When developing applications with high transaction rates, it is crucial to spread object metadata ownership across all
available regions. Doing so distributes potential metadata queries to all region managers in the system and insures a handful
of storages node aren’t stuck with the burden of serving layout information for all objects in the repository.

You should carefully consider your application’s object naming scheme and directory layout. Varying directory paths
spreads object management workload evenly across storage nodes. Concentrating objects to a small set of directory
paths can lead to network resource contention at a small set of region managers. Spreading them across a broader
directory structure will balance back-end network traffic, reduce I/O bottlenecks, and improve performance for
metadata-intensive I/O workloads.

3.2.2 Directory Layout

How data is laid out in a repository can have an impact on performance. You should carefully consider how
your application structures directories as it ingests data. In particular you should try to

 balance directory tree width and depth


 restrict directory tree depth to no more than 20 levels deep; flatter directory structures tend to operate more
efficiently

 distribute objects evenly amongst directories

Like most storage systems, HCP performs optimally within a set of engineered limits. In particular,
applications should be aware of published guidelines concerning

P a g e | 31
  maximum directories per configured system, and

 maximum objects per directory

Release notes documenting the latest recommended limits are published with every HCP release. You should
carefully consider your directory layout to insure these limits are not exceeded during the course of normal operation.

3.3 Protecting Objects

3.3.1 Authenticity and Checksums
When HCP creates an object it calculates a checksum for the object data it receives. The checksum is returned as
part of the HTTP response. Checksum values can be used by applications to ensure that data uploaded by the
PUT wasn't corrupted in-transit. Below is an example on how to generate an md5 hash.

1 public String MD5(String md5) {

2 try {
3 java.security.MessageDigest md = java.security.MessageDigest.getInstance(“MD5”);
4 byte[] array = md.digest(md5.getBytes());
5 StringBuffer sb = new StringBuffer();
6 for (int i = 0; i < array.length; ++i) {
7 sb.append(Integer.toHexString((array[i] & 0xFF) | 0x100).substring(1,3)):
8 }
9 return sb.toString():
10 } catch (java.security.NoSuchAlgorithmExcpetion e) {
11 }
12 return null;
13 }

P a g e | 32
3.3.2 Reliability
HCP provides a few ways to customize data reliability levels within a repository:

 RAID – All data stored on HCP is protected by RAID volumes. This is a standard protection
mechanism applied to all data on the repository.

 Data Protection Level – HCP can be configured to maintain multiple copies of an object to provide a higher
degree of protection against data loss and corruption. The number of copies is known as the data protection
level, or DPL. As of HCP 7.0 DPL can be configured via service plans, allowing different applications
accessing the same repository to have different levels of data reliability.

 Replication – For customers with the most stringent reliability needs, data can be replicated between HCP
systems. Replication is a must for applications with disaster recovery requirements. Replication can be
configured on a tenant-by-tenant basis.

You should carefully consider your data reliability needs, and consult your HCP administrator to help configure
the system to meet them.

3.4 Retaining Objects

3.4.1 Retention
Objects can be placed under retention. This guarantees their preservation for a specific length of time. HCP will reject
attempts to delete an object during its retention period. Retention settings are system metadata. You can use the
HCP REST API to manage system metadata for an object. See Section 2.4:

Retention settings can be expressed in a number of ways. HCP accepts two formats for specifying an absolute date
until which objects must be retained.

Format Description

Epoch Time Time in seconds since January 1, 1970. For instance

1279141446

translates to July 14, 2010 21:04:05 UTC

ISO 8601 Text-based representation of dates and times. For instance

2010-07-14T21:04:05-0000

translates to July 14, 2010 21:04:05 UTC

For example, appending the argument retention=1279141446 to a PUT request

String url = “http://example-ns01.example-tn01.hcp01.hitachi.com/rest/examples/world.txt" +

“?retention=1279141446”;

will cause the object examples/prunes.jpg to be retained until July 14, 2010 21:04:05 UTC.

As a convenience, retention can also be expressed as an offset from a well-known time. HCP supports a
simple convention that defines relative retention. Definitions begin with a well-known time

P a g e | 33
Symbol Description

R Current retention time of the object

A Creation time of the object

N Current time (NOW)

followed by an offset.

Symbol Description

y Years

M Months

w Weeks

d Days

h Hours

m Minutes

s Seconds

Together they define an absolute date for which an object must be retained. Offset symbols can be mixed and
matched to provide an accurate representation of your retention needs. For example,
String url = “http://example-ns01.example-tn01.hcp01.hitachi.com/rest/examples/world.txt"
+ “?retention=N+3Y-2M”;

will cause the object examples/prunes.jpg to be retained for 2 years and 10 months from the current time. HCP will
perform date-based arithmetic for you (in the order specified) to calculate the absolute timestamp it ultimately assigns.
A detailed summary of the retention format can be found in Section 6.3.5.

3.4.2 Retention Classes

You can also assign objects to retention classes. A retention class is a named setting that allows you to manage
retention settings for a group of objects. You can use them to consistently manage data that conform to a
particular rule or regulation.

Let’s look at an example. The administrator for the namespace ct.pacs.hcp01.hitachi.com repository needs to retain
objects stored in his namespace for a minimum of seven years. He creates a new retention class called

22CCR

to reflect the name of the regulation which drives his data retention needs. The syntax defining the retention
period should look familiar:

A+7y

Data bound to 22CCR will be retained for seven years from time of creation. Applications storing compliance data in
the ct.pacs namespace attach their object to the 22CCR retention class by using the retention URL parameter:

P a g e | 34
 String url = “http://example-ns01.example-tn01.hcp01.hitachi.com/rest/examples/world.txt"
+ “?retention=C+22CCR”;

Retention classes – like retention settings – are system metadata. You can use the HCP REST API to manage
system metadata for an object. See Section 2.4:

NOTE

If a retention class is deleted, the retention periods for objects will be set
to “deletion not allowed”. If a new retention class is set with the same
name the objects will inherit the retention settings of the new class.

3.4.3 Compliance Modes

Namespaces can be configured to enforce retention in two different ways: compliance mode and enterprise mode.

A namespace in compliance mode behaves like a traditional archive; any attempt to delete an object under retention
is rejected.

A namespace in enterprise mode is more flexible, and allows for audited deletion of objects under retention. Deleting
objects under retention from a namespace in enterprise mode requires Privileged Permissions. Privileged operations
work on an object-by-object basis and require you to specify a reason for each privileged transaction.

Let’s modify the program from Section 2.3 to perform a privileged delete.

1 public static void delete() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?" +
4 "privileged=true&reason=Because%20I%20Said%20So";
5
6 //create a new HttpClient object and a DELETE request object
7 HttpClient client = HttpClientBuilder.create().build();
8 HttpDelete request = new HttpDelete(url);
9
10 // add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
11 request.addHeader("Authorization", "HCP
12 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
13
14 //execute DELETE request
15 HttpResponse response = client.execute(request);
16
17 //print response status to console
18 System.out.println("Response Code : "
19 + response.getStatusLine().getStatusCode() + " " +
20 response.getStatusLine().getReasonPhrase());
21 }

P a g e | 35
You can specify the arguments privileged and reason as URL query parameters, or as form-encoded data.

NOTE

The reason for a privileged operation cannot exceed 1,024 characters

in length.

3.4.4 Legal Holds

Data access accounts with privileged permissions can place objects on legal hold to prevent them from being deleted.
An object on legal hold

 cannot be deleted, even by privileged operations


 cannot be versioned

 cannot have system metadata modified

Legal holds are useful when objects are needed for legal discovery. See Hitachi Content Platform: Using a
Namespace for more information on placing objects on legal hold.

WARNING!

Legal holds do not affect custom metadata. Objects under legal hold
can have their custom metadata modified without restriction.

3.5 Securing Objects

3.5.1 HTTPS
Customers with stringent internal data security requirements should strongly consider using HTTPS as a transport
protocol, especially when accessing objects in an HCP namespace. HCP namespaces require you to transmit static
security tokens as part of the HTTP header block. Attackers with internal access to your network infrastructure could
passively monitor network traffic to extract account credentials from unsecured REST transactions. Using HTTPS to
encrypt traffic makes it much more difficult for attackers to gain access to account passwords and impersonate valid
users. HTTPS imposes a modest impact on performance.

See the HCP Security Whitepaper for more details.

3.5.2 Access Control

Customers should strictly monitor data access accounts and their credentials. A well-understood set of permissions
and behaviors should be agreed upon by applications and administrators to limit unnecessary access to the
repository and minimize the effective attack footprint on the repository.

See the HCP Security Whitepaper for more details.

3.5.3 Data Encryption

Customers with stringent data leakage requirements should strongly consider enabling data-at-rest encryption
services. Data-at-rest encryption automatically encrypts all data stored on-disk, mitigating the risk of malicious data

P a g e | 36
extraction through the physical theft of one or more HCP components. Data-at-rest encryption imposes a impact on
over HCP performance.

See the HCP Security Whitepaper for more details.

3.5.4 Data Shredding

Customers with stringent requirements to prevent data leakage should strongly consider enabling data shredding
services. Data shredding securely deletes objects on-disk according to federal standards, mitigating the risk of
malicious data extraction through the physical theft of one or more HCP components. Data shredding imposes a
modest impact on performance.

P a g e | 37
4 Advanced Topics
4.1 Handling Errors
4.1.1 Retrying Transactions
You should retry an HTTP transaction if you are

 unable to establish a TCP session with HCP,


 the HTTP session terminates before HCP returns a response, or

 HCP returns a 503 Service Unavailable response

In the first two scenarios the most likely cause is the unanticipated failure of the storage node you are connected
to. HCP monitors the system at periodic intervals and diverts traffic from misbehaving components. You should
wait several seconds before retrying your transaction to provide HCP sufficient time to detect and correct any
issues it encounters.

Attempt Back-off Interval

1 15 secs

2 30 secs

3 60 secs

4.1.2 Dealing with Failed Writes

Incomplete PUT operations leave objects in an open state. Objects left in an open state are

 deletable, and

 overwritable

As recommended in Section 4.1.1: Retrying Transactions, you should retry failed PUT requests in the event
the transaction fails before a valid response code is issued.

4.2 Performance Programming

4.2.1 Concurrent Access
HCP is optimized for concurrent data access. Applications with large data sets can improve performance by breaking
them into discrete chunks and accessing them in parallel.

P a g e | 38
 NOTE

Each storage node is capable of handling 254 HTTP sessions

simultaneously. Exceeding this number will result in session queuing
and may introduce increased latencies.

Increasing the thread count and effective parallelism of your application will intensify load on HCP. Be sure to follow the
guidelines found in Section 3.1.1: Load Balancing to properly distribute traffic across storage nodes in the system.

Threads working in parallel should be directed against different directories, if possible. Section 3.2.1:
Region Management illustrates the impact of high traffic volume when leveraged against a single directory.

4.2.2 Persistent Connections

HCP supports HTTP/1.1 persistent connections. Persistent connections allow an application to re-use existing TCP
sessions to submit new HTTP requests. This circumvents the need to negotiate a TCP handshake for every HTTP
transaction. Apache will use persistent connections by default

4.3 Alternative I/O

4.3.1 Chunked Transfers
HCP supports HTTP/1.1 chunked transfer encoding. Chunked transfers are useful when you don’t know the size of
the object you’re attempting to upload. They are most typically used in streaming operations. Apache will
automatically determine whether or not chunked transfers should be used based on message content but it can
also forced. In our example from Section 2.1 we can add the following as line 38 to force chunked transfers

ByteArrayEntity requestEntity = new ByteArrayEntity(fileAsByteArr);

requestEntity.setChunked(true);

Chunked transfers impose a modest performance penalty relative to normal PUT requests. You should
carefully consider your application architecture before using this feature.

NOTE

The performance impact of chunked transfers is more pronounced

on namespaces with compression enabled.

4.3.2 Partial Content Transfers

HCP supports HTTP/1.1 partial content transfers. Partial content transfers allow you to download byte ranges from
an object. You can perform partial content transfers in Apache by adding a header to specify a range to download.
Let’s modify our simple download program from Section 2.1.1 to retrieve the first five bytes of the object
examples/world.txt.

P a g e | 39
 1 public static void get() throws IOException {
2 //specify namespace URL - eg. namespace.tenant.HCP.DOMAIN.com/rest/path
3 String url = "http://example-namespace.example-tenant.cluster59h-
4 vm3.lab.archivas.com/rest/examples/world.txt";
5
6 //create a new HttpClient object and a GET request object
7 HttpClient client = HttpClientBuilder.create().build();
8 HttpGet request = new HttpGet(url);
9
10 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
11 request.addHeader("Authorization", "HCP ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
12 request.addHeader("Range", "bytes=0-4");
13
14 //execute the request
15 HttpResponse response = client.execute(request);
16
17 //print response status to console
18 System.out.println("Response Code : "
19 + response.getStatusLine().getStatusCode() + " " +
20 response.getStatusLine().getReasonPhrase());
21
22 //get response content
23 BufferedReader rd = new BufferedReader(
24 new InputStreamReader(response.getEntity().getContent()));
25
26 //print response content to console
27 StringBuffer result = new StringBuffer();
28 String line = "";
29 while ((line = rd.readLine()) != null) {
30 result.append(line);
31 }
32 System.out.println(result.toString());
33 }

P a g e | 40
 NOTE

The performance impact of partial content transfers is more pronounced

when working on a namespace with compression enabled, or if the byte
range specified is small.

4.4 Versioning

4.4.1 Creating Versions

HCP supports the transparent versioning of objects. When versioning is enabled, adding an object to the
namespace with the same path and name as one that already exists automatically creates a new version of it.

By default, a new version of an object inherits metadata values from its immediate predecessor. You can override these
values by manually specifying different metadata values when you create the new version. See Section 2.4:

Versions are created using PUT requests. Section 2.1: Creating an Object provides a step-by-step tutorial on
creating new objects.

4.4.2 Retrieving Versions

HCP responds to PUT requests with the X-HCP-VersionId header when creating objects in a namespace with
versioning enabled.

X-HCP-VersionId: 79885459513089

X-HCP-VersionId is used to explicitly retrieve historic versions of objects. Let’s modify the program listing in Section 2.2.1
to retrieve a version of the object examples/world.txt with version identifier 79885459513089.

//specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path

String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?"
+ "version=79885459513098";

The GET method is used to retrieve historical versions of objects. The ID of the version to retrieve is specified in-
line as a URL parameter. The code required to download a specific version of an object otherwise remains the
same as the code required to download the current version. As always, object data is returned in the response body
on success.

4.4.3 Deleting Versions

If you delete an object from a namespace with versioning enabled, HCP will retain the object as a historic version.
HCP requires you to use the purge feature to delete all versions of an object from a namespace.

NOTE

You cannot delete individual historic versions of an object. You can only
purge them. When an object is purged from a repository, all its historic
versions are deleted.

Purging an object is similar to deleting one. Let’s modify the program in Section 2.3 to purge the
object examples/world.txt from the HCP namespace Ns01.

P a g e | 41
 String url = http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?"
+ "purge-true”;

The DELETE method is used to purge an object. The argument purge explicitly asks for the object to be purged from
the repository. It is specified in-line as a URL parameter.

If an object is on legal hold or under retention, a privileged purge is required to purge the object from the repository.
Privileged purges are described in greater depth in Section 3.4: Retaining Objects.

4.4.4 Listing Versions

You can query HCP to discover what versions of an object are being maintained in the repository. The response body
returned by HCP contains an XML document that lists the current and historic versions of an object and its metadata.
Let’s modify the program listing in Section 2.2.1 to retrieve a version list for the object examples/world.txt.
String url = http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt?" +
"version=list”;

The GET method is used to download version lists. Setting the URL query parameter version to a value of list
requests a version list to be returned in the response body.

An XML document listing all versions of the object is returned in lieu of object data:

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="/static/xsl/ns-versions.xsl"?> <versions
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/ns-versions.xsd"
path="/rest/examples/world.txt"
utf8path="/rest/examples/world.txt "
parentDir="/rest/examples">
utf8ParentDir="/rest/examples">
deleted="false"
showDeleted="true">
<entry urlName="world.txt"
utf8Name="world.txt"
type="object"
size="12"
hashScheme="SHA-256"
hash="D2A84F4B8B6..."
retention="0"
retentionString="Deletion Allowed"
retentionClass=""
ingestTime="1258469462"
ingestTimeString="11/17/2009 9:51AM"
hold="false"
shred="false"
dpl="2"
index="true"
customMetadata="false"
state="created"
version="80232488492929"
/>
<entry urlName="world.txt"
utf8Name="world.txt"
type="object"
size="14"
hashScheme="SHA-256"
hash="3672A83F3C0..."
retention="0"
retentionString="Deletion Allowed"
retentionClass=""
ingestTime="1258405200"
ingestTimeString="11/16/2009 4:00PM"
hold="false"
shred="false"
dpl="2"
index="true"

P a g e | 42
 customMetadata="false"
state="deleted"
version="80232488876481"
/>
</versions>

In this example we see that the object examples/world.txt has two versions: the current version and a historic one.
Metadata for each is returned as XML attributes. The version ID field can be used to retrieve a particular version of
the object. See Section 4.4.2: Retrieving Versions for more details on retrieving historic versions of an object.

For a summary of the XML format for version lists, see Section 6.3.6.1: Object versions. For a complete description of
the version list format, see Hitachi Content Platform: Using a Namespace.

4.5 Retrieving Status Information

4.5.1 Getting Object Information
It’s sometimes necessary for you to check a namespace for the existence of an object without downloading its
actual contents. This next program checks the HCP namespace ns01 for the existence of an object with path
examples/world.txt.

1 public static void head() throws IOException{

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/rest/examples/world.txt";
4
5 //create a new HttpClient object and a GET request object
6 HttpClient client = HttpClientBuilder.create().build();
7 HttpHead request = new HttpHead(url);
8
9 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
10 request.addHeader("Authorization", "HCP
11 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
12
13 //execute the request
14 HttpResponse response = client.execute(request);
15
16 //print response status to console
17 System.out.println("Response Code : "
18 + response.getStatusLine().getStatusCode() + " " +
19 response.getStatusLine().getReasonPhrase());
20
21 //get response content
22 BufferedReader rd = new BufferedReader(
23 new InputStreamReader(response.getEntity().getContent()));
24
25 //print response content to console
26 StringBuffer result = new StringBuffer();
27 String line = "";
28 while ((line = rd.readLine()) != null) {
29 result.append(line);
30 }
31 System.out.println(result.toString());
32 }

P a g e | 43
When you run this program, the HTTP request from your machine should look something like this:

Response Code : 200 OK

The HEAD method is used to retrieve information about an object. You can instruct Apache to issue HTTP HEAD
requests by creating an HttpHead object.

HEAD requests are used to determine if an object exists in a namespace, and returns system metadata for it if it does.

HTTP/1.1 200 OK
X-HCP-Time: 1259584200
Content-Type: text/plain
Content-Length: 12
X-HCP-Type: object
X-HCP-Size: 12
X-HCP-Hash: SHA-256 D2A84F4B8B6...
X-HCP-VersionId: 80205544854849
X-HCP-IngestTime: 1258469614
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: false
X-HCP-Custom-Metadata: false

For a list of commonly encountered headers and their function, see Section 6.3.3: Authenticated Namespaces. For a
full description of HCP response headers, see Hitachi Content Platform: Using a Namespace.

Apache does not print HTTP response headers by default. You can enable the output by adding the flags
described in Section 2.

4.5.2 Listing Directory Contents

It’s sometimes useful to programmatically list the contents of a directory. The following program returns the contents
of the directory examples in namespace ns01.

When you run this program, the HTTP request from your machine should look something like this:

Response Code : 200 OK

The GET method is used to retrieve directory listings. Setting the URL parameter type to the value directory will
cause HCP to return an XML document listing the contents of a directory.

Directory listings do not included deleted directories or objects by default. If the namespace supports versioning or
did in the past, you can request that previously deleted items be included in the result list.
String url = “http://example-ns01.example-tn01.hcp01.hitachi.com/rest/examples/?”
+ “type=directory&deleted=true”;

The XML document returned by HCP should look like this:

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="/static/xsl/ns-directory.xsl"?> <directory
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/ns-directory.xsd"
path="/rest/examples"
utf8Path="/rest/examples"

P a g e | 44
 parentDir="/rest">
utf8ParentDir="/rest"
dirDeleted="false"
showDeleted="true">
<entry urlName="world.txt"
utf8Name="world.txt"
type="object"
size="12"
hashScheme="SHA-256"
hash="D2A84F4B8B6..."
retention="0"
retentionString="Deletion Allowed"
retentionClass=""
ingestTime="1258392981"
ingestTimeString="11/16/2009 12:36PM"
hold="false"
shred="false"
dpl="2"
index="true"
customMetadata="false"
version="80238375537921"
state="created"
/>
<entry urlName="obsolete"
utf8Name="obsolete"
type="directory"
state="deleted"
/>
</directory>

4.5.3 Getting HCP Namespace Information

You can query HCP to learn what services your authenticated account has access to. In particular you can discover

 which HCP namespaces you can access with your account,


 what retention classes are defined for each of those namespaces,

 which operations you can perform in each of those namespaces, and

 retrieve statistics that provide information about the size and content of those namespaces

The GET method is used to access namespace information. The path in the URL specifies the type of
information being requested.

Path Summary

/proc Namespaces accessible with this account

/proc/permissions Permissions for this namespace with this account

/proc/retentionClasses Retention classes defined for this namespace

/proc/statistics Statistics for this namespace

P a g e | 45
 NOTE

You can directly view HCP namespace information from your

web browser.

Namespace information is returned as an XML document in the response body. Let’s modify the program in Section
2.2.1 to download statistics for the HCP namespace ns01.

1 public static void getStats() throws IOException {

2 //specify namespace URL - eg. ns01.tn01.hcp01.hitachi.com/rest/path
3 String url = "http://ns01.tn01.hcp01.hitachi.com/proc/statistics";
4
5 //create a new HttpClient object and a GET request object
6 HttpClient client = HttpClientBuilder.create().build();
7 HttpGet request = new HttpGet(url);
8
9 //add authorization header for user(base64) "exampleuser" with password(md5) "passw0rd"
10 request.addHeader("Authorization", "HCP
11 ZXhhbXBsZXVzZXI=:bed128365216c019988915ed3add75fb");
12
13
14 //execute the request
15 HttpResponse response = client.execute(request);
16
17 //print response status to console
18 System.out.println("Response Code : "
19 + response.getStatusLine().getStatusCode() + " " +
20 response.getStatusLine().getReasonPhrase());
21
22 //get response content
23 BufferedReader rd = new BufferedReader(
24 new InputStreamReader(response.getEntity().getContent()));
25
26 //print response content to console
27 StringBuffer result = new StringBuffer();
28 String line = "";
29 while ((line = rd.readLine()) != null) {
30 result.append(line);
31 }
32 System.out.println(result.toString());
33 }

P a g e | 46
HCP should return an XML document that looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="/static/xsl/proc-statistics.xsl"?> <statistics
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/proc-statistics.xsd"
namespaceName="ns01"
totalCapacity="10737418240"
usedCapacity="932454739"
softQuota="85"
objectCount="43230"
shredObjectCount="0"
shredObjectBytes="0"
customMetadataObjectCount="6754"
customMetadataObjectBytes="894893"
/>

You can parse this document programmatically to extract information of interest.

For a summary of the XML formats used by HCP to return namespace information, see Section 6.3.5: XML
Documents. For a full accounting of the XML formats, see Hitachi Content Platform: Using a Namespace.

P a g e | 47
5 Conclusions
By now you should know enough about HCP and the REST API to begin planning and developing useful applications.
HCP provides a strong foundation to develop highly reliable and secure applications suitable for use in the most
demanding environments.

P a g e | 48
6 Appendix
6.1 Code Availability
The code used in this example is available on publicly on GitHub for review and for use. It can be found at:

https://github.com/jhp612/HCPJavaRestSamples

Please note that the GitHub code has been optimized for use compared to the code used in this document which was
optimized for easy reference.

6.2 Supporting Libraries

6.2.1 Apache HTTP client
Apache HTTP Client is a client-side URL transfer library. It is covered by a modified MIT/X license and is freely
distributable. Apache supports a wide variety of HTTP and HTTP variants, and is widely used throughout the Internet.
It is highly portable, and works identically on a number of platforms, including Windows and a wide variety of UNIX
flavors.

You can find more information about Apache HTTP Client, including user manuals, API references, and sample code
at http://hc.apache.org/httpclient-3.x/

6.3 REST API Quick Reference

6.3.1 Request Methods
Method Description
GET Retrieves
  Objects
  Versions
  Version lists
  Directory listings
  Custom metadata
  Namespace lists
  Namespace statistics
  Namespace permissions
 Namespace retention classes

P a g e | 49
HEAD Checks existence of
  Objects
  Versions
  Directories
 Custom metadata

Retrieves
  Object metadata
 Version metadata

POST Modifies object metadata

  Legal hold
  Index settings
  Retention settings
 Shred settings

PUT Creates
  Objects
  Versions
  Empty directories
 Custom metadata

DELETE Removes
  Objects
  Versions
 Empty directories

6.3.2 Request Headers

6.3.2.1 Cookie
The Cookie header is used to transmit authentication tokens to HCP for validation. Valid tokens allow access to HCP
namespaces. Authentication tokens are defined as the base64 encoding of a valid account name concatenated with
an MD5 hash of its password, using a colon as a delimiter.

Cookie: authorization=HCP base64(acct-name):md5(acct-password)

See Section 2.1.1 a tutorial on using the Cookie header with the Apache HTTP library.

6.3.2.2 Range
The Range header is used for partial content transfers. User-defined byte ranges and offsets can be passed as
parameters in GET requests to vary the amount of data returned in the response.

Range: 0-2351

For a full description of range options, see Hitachi Content Platform: Using a Namespace.

6.3.2.3 Host
The Host header is used to identify an HCP system, its namespaces, and tenants. Namespaces are addressed by
hostname, arranged hierarchically as follows:

P a g e | 50
 Host: namespace.tenant.repository.domain.suffix

Host is used in conjunction with the Cookie header to authorize access to HCP namespaces. See Section 2.1.1 for a step-
by-step tutorial on using the Host header.

6.3.2.4 Transfer-Encoding
Transfer-Encoding is used for chunked content transfers.

Transfer-Encoding: chunked

Chunked transfers allow a client to upload data to the repository without initially knowing the total content length.
For more information on using chunked transfers, see Section 4.3.1: Chunked Transfers.

6.3.3 Response Codes

Status Summary Methods Description
200 OK GET Successfully retrieved object, directory, or
HEAD metadata
POST
DELETE Successfully set metadata value

Successfully deleted object, directory, or custom

metadata

201 Created PUT Successfully added object, version, directory, or

custom metadata

Successfully replaced custom metadata

204 No Content GET Object does not have custom metadata

HEAD
Requested version has been pruned and is no
longer available

206 Partial Content GET Successfully retrieved requested byte range

302 Found ALL hcp-ns-auth cookie missing

Invalid authentication credentials

400 Bad Request ALL Malformed URL

Unsupported or invalid value for a parameter

Attempt to modify retention from class setting to

an absolute date value

Attempt to set retention for object under legal hold

Attempt to disable data shredding

Malformed custom metadata XML document

P a g e | 51
 401 Unauthorized ALL Insufficient privileges

403 Forbidden ALL Insufficient privileges

Namespace does not exist

Access method (HTTP/HTTPS) disabled

Attempt to delete object under retention

Attempt to delete non-empty directory

Attempt to version object under retention

404 Not Found DELETE Could not find object, version, or directory
GET
HEAD Requested version is the current version of
POST deleted object
PUT

409 Conflict DELETE Attempt to delete object currently being written

PUT
Object already exists and versioning is not
enabled (WORM)

Attempt to version an object currently being

written

413 File Too Large PUT Insufficient capacity to store object

414 Request URI Too ALL URL following /rest prefix longer than 4,095 bytes
Large
416 Requested Range GET Start position greater than size of requested data
Not Satisfied
Byte range is size zero

500 Internal Server Error ALL Internal error. Please contact namespace
administrator

503 Service Unavailable ALL Repository temporarily unable to handle request

6.3.4 Response Headers

6.3.4.1 Authenticated Namespaces

Header Description

X-HCP-Custom-Metadata Boolean value indicating whether object has custom

metadata associated with it

P a g e | 52
X-HCP-DPL Data protection level of the object

X-HCP-Hash Cryptographic hash algorithm and value of the stored

object or version

X-HCP-Index Boolean value indicating whether the object can be

indexed

X-HCP-IngestTime Object creation timestamp, in Epoch time

X-HCP-Type Object entity type. This is always object for objects and
versions of objects.

X-HCP-Retention End of the object’s retention period, in Epoch time.This

value can also be 0 (deletion allowed), -1 (deletion
prohibited), or -2 (unspecified)

X-HCP-RetentionClass Name of the retention class assigned to the object. This

value is an empty string if the object has not been assigned
a retention class.

X-HCP-RetentionHold Boolean value indicating whether the object is on legal

hold.

X-HCP-RetentionString End of the object’s retention period, in the following format:

week-day month day hh:nn:ss time-zone year

This value can also be Deletion Allowed, Deletion

Prohibited, or Initial Unspecified

X-HCP-Shred Boolean value indicating whether object should be

shredded for deletion

X-HCP-Size Size of the object, in bytes

X-HCP-VersionId Version identifier of the object

6.3.5 Retention Syntax

6.3.5.1 Absolute Dates

Every object, including objects assigned to retention classes, has a retention setting that specifies when (or
whether) the retention period for it ends.

Numeric Value Description

-2 The object does not have a retention setting. It

cannot be deleted, except by privileged delete.
This setting can be changed.

-1 The object cannot be deleted, except by

P a g e | 53
 privileged delete. This setting cannot be changed.

0 The object can be deleted at any time. This

setting can be changed.

Timestamp (Epoch) The object cannot be deleted until the specified

date and time, except by privileged delete.

6.3.5.2 Relative Dates

Retention settings can be defined as offsets from a well-known time. HCP defines relative dates by using the syntax

([RAN])?([+-]\d+y)?([+-]\d+M)?([+-]\d+w)?([+-]\d+d)?([+-]\d+h)?([+-]\d+m)?([+-]d+s)?

Symbol Description

R Current retention time

A Object creation time

N Current time

y Years

M Months

w Weeks

d Days

h Hours

m Months

s seconds

6.3.5.3 Classes
You can bind an object to a retention class by using the syntax

C+class-name

For instance, the syntax for binding an object to the class jamba would be

C+jamba

6.3.6 XML Documents

6.3.6.1 Object versions

Version listings consist of a top level versions element which describes the object in question and a series of entry
elements that describe each version. The template for the XML document is:

<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl"

href="/static/xsl/ns-versions.xsl"?>

P a g e | 54
 <versions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/ns-versions.xsd"
path="object-path"
utf8Path="object-path"
parentDir="parent-directory-path"
utf8ParentDir="parent-directory-path"
deleted="true|false"
showDeleted="true|false">
<entry urlname="object-name"
utf8Name="object-name"
type="object"
size="size-in-bytes"
hashScheme="hash-algorithm"
hash="hash-value"
retention="retention-seconds-after-1/1/1970"
retentionString="retention-datetime-value"
retentionClass="retention-class-name"
ingestTime="ingested-seconds-after-1/1/1970"
ingestTimeString="ingested-datetime"
hold="true|false"
shred="true|false"
dpl="dpl"
index="true|false"
custom-metadata="true|false"
state="created|deleted"
version=version-id"
/>
...
</versions>

6.3.6.2 Accessible namespaces

Namespace listings consist of a top-level namespaces element and a series of namespace elements that describe
each namespace accessible to the user. The template for the XML document is:

<?xml version=”1.0” encoding=”UTF-8”?>

<?xml-stylesheet type="text/xsl" href="/static/xsl/proc-namespaces.xsl"?>
<namespaces xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/proc-namespaces.xsd"
tenantHostName="tenant-name.hcp-name.domain-name"
httpScheme="http">
<namespace name="namespace-name"
nameIDNA="namespace-url-name"
versioningEnabled="true|false"
searchEnabled="true|false"
retentionMode="compliance|enterprise"
defaultShredValue="true|false"
defaultIndexValue="true|false"
defaultRetentionValue="retention-setting"
hashScheme="hash-algorithm"
dpl="data-protection-level">
<description><![CDATA[
namespace-description
]]></description>
</namespace>
...
</namespaces>

6.3.6.3 Retention classes

Retention class listings consist of a top-level retentionClasses element and a series of retentionClass elements that
describe each retention class associated with the namespace. The template for the XML document is:

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="/static/xsl/proc-retention-classes.xsl"?>
<retentionClasses xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/proc-retention-classes.xsd"
namespaceName="namespace-name">
<retentionClass
name="class-name"

P a g e | 55
 value="retention-value">
autoDelete="true|false"
<description><![CDATA[
class-description
]]></description>
</retentionClass>
...
</retentionClasses>

6.3.6.4 Namespace and user permissions

Permission listings consist of a top-level permissions element followed by a fixed number of permission elements that
describe permissions assigned to the user. The template for the XML document is:

<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl"

href="/static/xsl/proc-permissions.xsl"?> <permissions
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/proc-permissions.xsd"
namespaceName="namespace-name">
<namespacePermissions
read="true|false"
write="true|false"
delete="true|false"
privileged="true|false"
purge="true|false"
search="true|false"/>
<namespaceEffectivePermissions
read="true|false"
write="true|false"
delete="true|false"
privileged="true|false"
purge="true|false"
search="true|false"/>
<userPermissions
read="true|false"
write="true|false"
delete="true|false"
privileged="true|false"
purge="true|false"
search="true|false"/>
<userEffectivePermissions
read="true|false"
write="true|false"
delete="true|false"
privileged="true|false"
purge="true|false"
search="true|false"/>
</permissions>

6.3.6.5 Namespace statistics

Namespace statistics consist of a single statistics element that encapsulates a number of statistical properties as
attributes. The template for the XML document is:

<?xml-stylesheet type="text/xsl" href="/static/xsl/proc-statistics.xsl"?> <statistics

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="/static/xsd/proc-statistics.xsd"
namespaceName=namespace-name"
totalCapacityBytes="total-capacity-bytes"
usedCapacityBytes="used-capacity-bytes"
softQuotaPercent="soft-quota-percentage"
objectCount="number-of-objects"
shredObjectCount="number-of-objects-to-be-shredded"
shredObjectBytes="bytes-to-be-shredded"
customMetadataObjectCount="number-of-objects-with-custom-metadata"
customMetadataObjectBytes="bytes-of-custom-metadata"
/>

P a g e | 56