Posted Mar 24 by Peng Qiu.
Updated Mar 24.

In this tutorial, we will show you how to manage lightweight objects in Documentum REST Services.

Last activity Mar 24 by Peng Qiu.
41 views. 0 comments.

Overview

Lightweight object types are special object types in Documentum used to minimize the storage space for multiple objects who share same metadata. Documentum REST Services (Core REST) adds full support for the lightweight object operations. This tutorial will cover these contents for them.

  • Shareable and lightweight object types
  • Create shareable and lightweight objects
  • Materialize and dematerialize lightweight objects
  • Reparent lightweight objects

Shareable and lightweight object types

All lightweight object types, or called lightweight types, are special subtypes of shareable object types, or called shareable types. Every lightweight type has one shareable parent type. When a lightweight object is being created, it must reference a shareable object.

create shareable and lightweight types

Before trying out the samples in next sections, you'll need create your own shareable and lightweight object types in the Documentum Composer, which can be found at https://knowledge.opentext.com. In order to use lightweight types related features in Composer, a lightweight SysObject plugin is also needed. The detailed guides for installation and lightweight object management can be referenced in the Documentum Composer User Guide.

After your Composer and plugin are installed, you can create a shareable object type. Through the Composer UI, you can configure your own attributes for that type. Note that the property Supertype must be chosen and a checkbox named Is Shareable have to be ticked when you are designing the shareable type.

enter image description here

After the steps above are finished, you can create a lightweight type based on the shareable type you have just created. Make sure your shareable type is selected for the property Shared Parent.

enter image description here

When these two types are saved, install your Documentum project in the Composer. Then, your types are generated in a repository.

retrieve shareable and lightweight types

Both shareable and lightweight types can be obtained from the Type(s) Resource in Core REST, distinguished by the property type_category.

  • type_category=2 means shareable types
  • type_category=4 means lightweight types

The query parameter filter can be used to retrieve them. Sample URIs are as follows.

  • GET /dctm-rest/repositories/{repositoryName}/types?filter=type_category=2
  • GET /dctm-rest/repositories/{repositoryName}/types?filter=type_category=4

Since release 7.3, the Type Resource has improved in these aspects:

  • Two new properties are added
  • shared-parent: the URI of the parent shareable type, available only if it is a lightweight type
  • category: the category of the type, can be one of aspect, shareable, lightweight, data table and standard
{
    "name": "my_lightweight_type",
    "label": "Sysobject",
    "category": "lightweight",
    "parent": "http://your_host_or_IP:8080/dctm-rest/repositories/REPO1/types/my_shareable_type",
    "shared-parent": "http://your_host_or_IP:8080/dctm-rest/repositories/REPO1/types/my_shareable_type",
    "ignore-parent-constraints": false,
    ...
}
  • Two new link relations are added
  • http://identifiers.emc.com/linkrel/parent-shareable-type: available for lightweight types, to
    get their parent shareable types
  • http://identifiers.emc.com/linkrel/lightweight-types: available for shareable types, to get their
    child lightweight types

Create shareable and lightweight objects

Create a shareable object

Since multiple lightweight objects can share a shareable object, before creating the lightweight object, a shareable object must be created first. The shareable object can be created as a normal SysObject, except the object type defined as a shareable one.

POST /dctm-rest/repositories/REPO1/folders/0b00000280002934/objects HTTP/1.1
Host: your_host_or_IP:8080
Content-Type: application/json

{
  "properties": {
      "object_name": "customer-1",
      "r_object_type": "my_shareable_type"
  }
}

Once the object is created, there will be a new link relation on the shareable object, http://
identifiers.emc.com/linkrel/lightweight-objects. Following this link, you can GET all lightweight objects that share this object's attributes, or POST to create a new lightweight object for this shareable object.

{
    "name": "object",
    "type": "my_shareable_type",
    "definition": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/types/my_shareable_type",
    "properties": {
        "object_name": "customer-1",
        "r_object_type": "my_shareable_type",
        ...
        "r_object_id": "08000002800039ae"
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/lightweight-objects",
            "href": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/objects/08000002800039ae/lw-objects"
        },
        ...
    ]
}

Create a lightweight object

As this is a newly created shared object, it does not have any lightweight objects under it. Here we are going to create a new lightweight object. So following the link relation http://identifiers.emc.com/linkrel/lightweight-objects, you can make a POST request. The request body is same as a normal sysobject, except the object type defined as a lightweight one.

POST /dctm-rest/repositories/REPO1/objects/08000002800039ae/lw-objects HTTP/1.1
Host: your_host_or_IP:8080
Content-Type: application/json

{
  "properties": {
      "object_name": "order-1",
      "r_object_type": "my_lightweight_type"
  }
}

Other operations like update, delete, etc., are exactly the same as those of an ordinary SysObject.

Materialize and Dematerialize a lightweight object

If a lightweight object has changed any property inherited from its parent shareable object, the object is called materialized. According to Documentum internal storage mechanisms, a materialized object will have its own private copy of the parent object. You can reference the Documentum Server Fundamentals Guide for the details.

Only A dematerialized lightweight object can be materialized. And vice versa, a materialized lightweight object can be dematerialized. The dematerialization means that the lightweight object abandons its private copy of the parent, and re-shares the original shareable object.

distinguish a materialized/dematerialized object

In Documentum REST services, users can use the link relations to distinguish whether a lightweight object is materialized or dematerialized. The default lightweight object is dematerialized. Let's take the lightweight object we've just created as an example.

GET /dctm-rest/repositories/REPO1/objects/08000002800039af HTTP/1.1
Host: your_host_or_IP:8080

We can find the link relation http://idetifiers.emc.com/linkrel/materialize on its resource representation. Besides, the property i_sharing_parent is pointing to the parent shareable object we have generated in the previous section. Both indicates that it is a dematerialized object.

{
    "name": "object",
    "type": "my_lightweight_type",
    "definition": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/types/my_lightweight_type",
    "properties": {
        "object_name": "order-1",
        "r_object_type": "my_lightweight_type",
        ...
        "i_sharing_parent": "08000002800039ae",
        "r_object_id": "08000002800039af"
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/materialize",
            "href": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/objects/08000002800039af/materialization"
        },
        ...
    ]
}

materialize a lightweight object

Users can materialize a lightweight object in two ways. First, you can make a PUT request to the link relation we've mentioned in the last section. Through this method, the object would be materialized even no property is changed at all. Here is an example.

PUT /dctm-rest/repositories/REPO1/objects/08000002800039af/materialization HTTP/1.1
Host: your_host_or_IP:8080

An updated representation will be responded as follows. A link relation for dematerializing rather than materializing is shown on the resource. The property i_sharing_parent is pointing to the lightweight object's own id, while the property i_orig_parent is still pointing to its original parent.

{
    "name": "object",
    "type": "my_lightweight_type",
    "definition": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/types/my_lightweight_type",
    "properties": {
        "object_name": "order-1",
        "r_object_type": "my_lightweight_type",
        ...
        "i_orig_parent": "08000002800039ae",
        "i_sharing_parent": "08000002800039af",
        "r_object_id": "08000002800039af"
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/dematerialize",
            "href": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/objects/08000002800039af/materialization"
        },
        ...
    ]
}

Another way to perform the materialization is updating an inherited property of the lightweight object directly, through which the object will be materialized automatically. Here's an example. The property my_cust_name is an attribute belonged to the shareable type my_shareable_type, in other words, it is an attribute inherited by the lightweight object.

POST /dctm-rest/repositories/REPO1/objects/08000002800039af HTTP/1.1
Host: your_host_or_IP:8080
Content-Type: application/json

{
  "properties": {
      "my_cust_name": "Tom"
  }
}

Just like the previous method, the link relation for dematerializing and related properties will be shown and changed as expected.

{
    "name": "object",
    "type": "my_lightweight_type",
    "definition": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/types/my_lightweight_type",
    "properties": {
        "object_name": "order-1",
        "r_object_type": "my_lightweight_type",
        ...
        "my_cust_name": "Tom",
        ...
        "i_sharing_parent": "08000002800039af",
        "r_object_id": "08000002800039af"
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/dematerialize",
            "href": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/objects/08000002800039af/materialization"
        },
        ...
    ]
}

dematerialize a lightweight object

Compared to the materialization, the dematerialization is very plain. Following the link relation http://identifiers.emc.com/linkrel/dematerialize, and simply make a DELETE request to the materialized object will get the job done.

DELETE /dctm-rest/repositories/REPO1/objects/08000002800039af/materialization HTTP/1.1
Host: your_host_or_IP:8080

A 204 No Content would be returned if the dematerialization has finished. If you GET the lightweight object now, you will find that the object is referred to the original parent and all inherited properties are reverted.

Reparent a lightweight object

A lightweight object can be reparented to another shareable object, to share the metadata of the new parent. Reparenting is only valid for lightweight objects.

{
    "name": "object",
    "type": "my_lightweight_type",
    "definition": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/types/my_lightweight_type",
    "properties": {
        "object_name": "order-1",
        "r_object_type": "my_lightweight_type",
        ...
        "i_sharing_parent": "08000002800039ae",
        "r_object_id": "08000002800039af"
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/shared-parent",
            "href": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/objects/08000002800039af/parent"
        },
        ...
    ]
}

You can make a POST request to the link relation http://identifiers.emc.com/linkrel/shared-parent with the object href which contains an URI of the new parent shareable object.

POST /dctm-rest/repositories/REPO1/objects/08000002800039af/parent HTTP/1.1
Host: your_host_or_IP:8080
Content-Type: application/json

{
  "href": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/objects/08000002800039ae"
}

The property i_sharing_parent will be changed to the new parent's id, if the operation has succeeded. A tricky thing here is that a lightweight will also be dematerialized if you reparent it to its original parent object.

{
    "name": "object",
    "type": "my_lightweight_type",
    "definition": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/types/my_lightweight_type",
    "properties": {
        "object_name": "order-1",
        "r_object_type": "my_lightweight_type",
        ...
        "my_cust_name": "",
        "i_orig_parent": "08000002800039ae",
        "i_sharing_parent": "08000002800039ae",
        "r_object_id": "08000002800039af"
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/materialize",
            "href": "http://<your_host_or_IP>:8080/dctm-rest/repositories/REPO1/objects/08000002800039af/materialization"
        },
        ...
    ]
}

Table of Contents

Your comment

To leave a comment, please sign in.