Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Working with directories


HCP lets you perform these operations on directories:

Creating an empty directory

Checking the existence of a directory

Listing directory contents

Creating an empty directory

This chapter describes these procedures.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Creating an empty directory


You use the HTTP PUT method to create empty directories in a namespace. If any other directories in the path you specify for a new directory do not already exist, HCP creates them as well.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request contents (PUT directory)


The PUT request to create an empty directory has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header

A URL specifying the location in which to create the directory

A type URL query parameter with a value of directory

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (PUT directory)


To create a directory, you need write permission for the namespace.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific return codes (PUT directory)


The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.

Code Meaning Description
201 Created

HCP successfully created the directory.

409 Conflict

HCP could not create the directory in the namespace because a directory, object, or symbolic link with the specified name already exists.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific response headers (PUT directory)


This creation operation does not return any request-specific response headers. For information on all HCP-specific response headers, see HCP-specific HTTP response headers.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Example: Creating an empty directory


Here’s a sample HTTP PUT request that creates a new directory named graphics in the quarterly_rpts directory.

Request with curl command line

curl -k -iX PUT
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.c..._rpts/graphics
    ?type=directory"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/graphics?type=directory")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "PUT")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

 

Request headers

PUT /rest/quarterly_rpts/graphics?type=directory HTTP/1.1
Host: finance.europe.hcp.example.com
Authorizaton: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
Location: /rest/quarterly_rpts/graphics
Content-Length: 0

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Checking the existence of a directory


You use the HTTP HEAD method to check whether a directory exists in a namespace.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request contents (HEAD directory)


The HEAD request to check the existence of a directory has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header

The URL of the directory

By default, you can't check the existence of a directory if it has been deleted. If the namespace supports versioning, you can check for deleted objects and directories. To do this, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (HEAD directory)


To check for directory existence, you need browse permission.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific return codes (HEAD directory)


The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.

Code Meaning Description
200 OK

HCP found a directory or object at the specified URL.

404 Not Found

One of:

HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory that has been deleted.

Any component of the URL except for the last component in the path is a symbolic link to a directory.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific response headers (HEAD directory)


The table below describes the request-specific response headers for this operation. For information on all HCP-specific response headers, see HCP-specific HTTP response headers.

Header Description

X-HCP-Type

The type of the entity. This value is always directory for directories.

X-HCP-ChangeTimeMilliseconds

The change time for the directory, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that’s unique for the change time (for example, 1336483100178.00).

The change time for a directory is the most recent of:

The time the directory was created

The time the directory was deleted

The time an object was added to the directory

The time an object was deleted from the directory

X-HCP-ChangeTimeString

The change time for the directory in this format:

yyyy-MM-ddThh:mm:ssZ

In this format, Z represents the offset from UTC and is specified as:

(+|-)hhmm

For example, 2012-05-08T09:18:20-0400 represents the start of the 20th second into 9:18 AM, May 8, 2012, EDT.

X-HCP-SymlinkTarget

The path to the target directory as specified when the directory was created.

This header is returned only if the request URL specifies a symbolic link to a directory.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Example: Checking the existence of a directory


Here’s a sample HTTP HEAD request that checks the existence of a directory named quarterly_rpts.

Request with curl command line

curl -k -iI -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.c...quarterly_rpts"

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HEADER, 1)
curl.setopt(pycurl.NOBODY, 1)
curl.setopt(pycurl.WRITEFUNCTION, cin.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
print cin.getvalue()
curl.close()

 

Request headers

HEAD /rest/quarterly_rpts HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334829227
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xm
X-HCP-ChangeTimeMilliseconds: 1326336965436
X-HCP-ChangeTimeString: 2012-01-11T09:56:05-0500
X-HCP-Type: directory
Content-Length: 0

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Listing directory contents


You use the HTTP GET method to list the contents of a directory in a namespace. This method does not list old versions of objects.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request contents (GET directory)


The GET request to list a directory contents has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header

The URL of the directory

Listing deleted objects and directories

By default, a directory list does not include deleted objects or directories. If the namespace supports versioning, you can include deleted objects and directories in the list. To do this, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

Also specify the deleted=true parameter to list the contents of a deleted directory (which can contain only deleted objects and directories).

Managing subdirectory change times

By default, the change time returned for each subdirectory in a directory list is the time the subdirectory was created or, if the subdirectory is a deleted directory, the time it was deleted. You can choose instead to return change times that are the most recent of:

The time the subdirectory was created

The time the subdirectory was deleted

The time an object was most recently added to the subdirectory

The time an object was most recently deleted from the subdirectory

To do this, specify this URL query parameter:

mostRecentDirTimes=true

You can also specify mostRecentDirTimes=false, which results in the default behavior.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (GET directory)


To list the contents of a directory, you need browse permission.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific return codes (GET directory)


The table below describes the HTTP return codes that have specific meaning for this request. For descriptions of all possible return codes, see HTTP return codes.

Code Meaning Description
200 OK

HCP successfully retrieved the directory listing. This code is also returned if the URL specified an object and HCP successfully retrieved the object.

404 Not Found

One of:

HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory that has been deleted.

Any component of the URL except for the last component in the path is a symbolic link to a directory.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific response header (GET directory)


The table below describes the request-specific response header for this operation. For information on all HCP-specific response headers, see HCP-specific HTTP response headers.

Header Description

X-HCP-Type

The type of the entity. This value is always directory for directories.

X-HCP-ChangeTimeMilliseconds

The change time for the directory, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that’s unique for the change time (for example, 1336483100178.00).

The change time for a directory is the most recent of:

The time the directory was created

The time the directory was deleted

The time an object was most recently added to the directory

The time an object was most recently deleted from the directory

X-HCP-ChangeTimeString

The change time for the directory in this format:

yyyy-MM-ddThh:mm:ssZ

In this format, Z represents the offset from UTC and is specified as:

(+|-)hhmm

For example, 2012-05-08T09:18:20-0400 represents the start of the 20th second into 9:18 AM, May 8, 2012, EDT.

X-HCP-SymlinkTarget

The path from the symbolic link to the target directory as specified when the symbolic link was created.

This header is returned only if the request URL specifies a symbolic link to a directory.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Response body (GET directory)


The body of the HTTP response consists of XML that lists the contents of the requested directory, including metadata for the objects the directory contains. It lists only the immediate directory contents, not the contents of any subdirectories.

The XML for the list has this format:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/directory.xsl"?>
<directory xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="/static/xsd/directory.xsd"
    path="directory-path"
    utf8Path="utf8-directory-path"
    parentDir="directory-path"
    utf8ParentDir="utf8-directory-path"
    dirDeleted="true|false"
    showDeleted="true|false"
    namespaceName="namespace-name"
    utf8NamespaceName="utf8-namespace-name">
    changeTimeMilliseconds="change-milliseconds-after-1/1/1970.unique-integer

    changeTimeString="yyyy-MM-ddThh:mm:ssZ"

    <!-- Format for a subdirectory -->
    <entry urlName="directory-name"
        utf8Name="utf8-directory-name"
        type="directory"
        changeTimeMilliseconds="change-milliseconds-after-1/1/1970.unique-integer

        changeTimeString="yyyy-MM-ddThh:mm:ssZ"
        state="created|deleted"
    />

    <!-- Format for a symbolic link -->
    <entry urlName="symbolic-link-name"
        utf8Name="utf8-symbolic-link-name"
        type="symlink"
        symlinkTarget="path-to-target"
        utf8SymlinkTarget="utf8-path-to-target"
        state="created|deleted"
    />

    <!-- Format for an object -->
    <entry urlName="object-name"
        utf8Name="utf8-object-name"
        type="object"
        size="object-size-in-bytes"
        etag="etag"
        hashScheme="hash-algorithm"
        hash="hash-value"
        retention="(retention-seconds-after-1/1/1970|0|-1|-2)"
        retentionString="(retention-datetime-value|Deletion Allowed|
            Deletion Prohibited|Initial Unspecified)"
        retentionClass="[retention-class-name]"

        ingestTime="ingest-seconds-after-1/1/1970"
        ingestTimeString="MM/dd/yyyyhh:mm(AM|PM)"
        hold="true|false"
        shred="true|false"
        dpl="data-protection-level"
        index="true|false"
        customMetadata="true|false"
        customMetadataAnnotations="semicolon-delimited list of annotations"
        version="version-number"
        replicated="true|false"
        changeTimeMilliseconds="change-milliseconds-after-1/1/1970.unique-integer"

        changeTimeString="yyyy-MM-ddThh:mm:ssZ"
        owner="[username|nobody]"
        domain="[active-directory-domain]"
        hasAcl="true|false"
        state="created|deleted"
    />

</directory>

In this format:

The hashScheme and hash attributes are not returned for multipart objects.

The ingestTimeString and retentionString values are in the time zone of the HCP system. For example, if the repository is in Boston, Massachusetts and the ingestTime is 1330626356 (which corresponds to 3/1/2012 18:25:56 UTC), the ingestTimeString value is 3/1/2012 2:25PM.

The changeTimeString value is in ISO 8601 format, which is the time in the time zone of the HCP system followed by the hour and minute offset between local time and UTC.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Example: Listing the contents of a directory that includes deleted objects


Here’s a sample HTTP GET request that lists all the contents, including any deleted objects or subdirectories, of a directory named quarterly_rpts in a namespace that supports versioning.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.c...s?deleted=true"
    > quarterly_rpts.xml

Request in Python using PycURL

import pycurl
filehandle = open("quarterly_rpts.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts?deleted=true")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

 

Request headers

GET /rest/quarterly_rpts?deleted=true HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1335036864
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
X-HCP-Type: directory
X-HCP-ChangeTimeMilliseconds: 1353420657688.00
X-HCP-ChangeTimeString: 2012-11-20T09:10:57-0500
Content-Length: 577

Response body

<?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/quarterly_rpts"
    utf8Path="/rest/quarterly_rpts"
    parentDir="/rest">
    utf8ParentDir="/rest"
    dirDeleted="false"
    showDeleted="true"
    namespaceName="finance"
    utf8NamespaceName="finance">
    changeTimeMilliseconds="1326336965436"
    changeTimeString="2012-01-11T09:56:05-0500"

    <entry urlName="Q4_2011.ppt"
         utf8Name="Q4_2011.ppt"
         type="object"
         size="671744"
         hashScheme="SHA-256"
         hash="42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736EF367..."
         retention="0"
         retentionString="Deletion Allowed"
         retentionClass=""
         ingestTime="1326898187"
         ingestTimeString="1/18/2012 2:49PM"
         hold="false"
         shred="false"
         dpl="2"
         index="true"
         customMetadata="false"
         customMetadataAnnotations=""
         version="80238375537921"
         replicated="false"
         changeTimeMilliseconds="1326898187533.00"
         changeTimeString="2012-01-18T14:49:47-0400"
         owner="lgreen"
         domain=""
         hasAcl="false"
         state="created"
    />
    <entry urlName="obsolete"
         utf8Name="obsolete"
         type="directory"
         changeTimeMilliseconds="1331847677748.00"
         changeTimeString="2012-03-15T17:41:17-0400"
         state="deleted"
    />
    <entry urlName="Q1_2012.ppt"
         utf8Name="Q1_2012.ppt"
         type="object"
         size="678400"
         hashScheme="SHA-256"
         hash="E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1C257C01..."
         retention="0"
         retentionString="Deletion Allowed"
         retentionClass=""
         ingestTime="1334847117"
         ingestTimeString="4/19/2012 9:51AM"
         hold="false"
         shred="false"
         dpl="2"
         index="true"
         customMetadata="false"
         customMetadataAnnotations=""
         version="80238376132993"
         replicated="false"
       changeTimeMilliseconds="1334847117598.00"
         changeTimeString="2012-04-19T09:51:57-0400"
         owner="lgreen"
         domain=""
         hasAcl="false"
         state="created"
    />
</directory>

Notice that the obsolete directory was deleted. It does not appear in a directory listing if the URL does not include the deleted=true parameter.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Deleting an empty directory


You use the HTTP DELETE method to delete an empty directory from a namespace. You cannot delete a directory that contains any objects, subdirectories, or symbolic links.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request contents (DELETE directory)


The DELETE request to delete an empty directory has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header

The URL of the directory

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Access permission (DELETE directory)


To delete a directory you need delete permission for the namespace.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific return codes (DELETE directory)


The table below describes the HTTP return codes that have specific meanings for this request. For descriptions of all possible return codes, see HTTP return codes.

Code Meaning Description
200 OK

HCP successfully deleted the directory.

400 Bad Request

The request specified a conditional header, such as If-Match.

If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header.

403 Forbidden

One of:

The Authorization header or hcp-ns-auth cookie specifies invalid credentials.

The namespace requires client authentication, and the request does not have an Authorization header or hcp-ns-auth cookie.

The specified directory is not empty.

The user doesn’t have delete permission.

The namespace does not exist.

The access method (HTTP or HTTPS) is disabled.

If more information about the error is available, the response headers include the HCP-specific X‑HCP-ErrorMessage header.

404 Not Found

One of:

HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory that has been deleted.

Any component of the URL except for the last component in the path is a symbolic link to a directory.

409 Conflict

HCP could not delete the specified directory because the directory is currently being written to the namespace.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request-specific response headers (DELETE directory)


This operation does not return any request-specific response headers. For information on all HCP-specific response headers, see HCP-specific HTTP response headers.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Example: Deleting an empty directory


Here’s a sample HTTP DELETE request that deletes the directory named obsolete from the quarterly_rpts directory in the namespace.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
   "https://finance.europe.hcp.example.c..._rpts/obsolete

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/obsolete")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

 

Request headers

DELETE /rest/quarterly_rpts/obsolete HTTP/1.1
Host:
finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334829227
Content-Length: 0
0

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

 

  • Was this article helpful?