From 956f8dc90c531bb469beac761d3bc8ff5e4a3947 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Thu, 11 Apr 2013 15:01:32 +0000
Subject: [PATCH] CR-1537 Fix for OPENDJ-847: Document REST delete support

---
 opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml |  225 +++++++++++++++++++++++++++++++++++++-------
 opendj3/src/site/resources/Example.ldif                      |   46 ++++++++
 2 files changed, 230 insertions(+), 41 deletions(-)

diff --git a/opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml b/opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml
index b8002ac..bf177c7 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml
+++ b/opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml
@@ -148,6 +148,7 @@
 
     <screen>$ curl
  --request PUT
+ --user kvaughan:bribery
  --header "Content-Type: application/json"
  --header "If-None-Match: *"
  --data '{
@@ -170,12 +171,8 @@
  }'
  http://opendj.example.com:8080/users/newuser?_prettyPrint=true
 {
-  "_rev" : "0000000035c03ca9",
+  "_rev" : "000000005b337348",
   "schemas" : [ "urn:scim:schemas:core:1.0" ],
-  "manager" : [ {
-    "_id" : "kvaughan",
-    "displayName" : "Kirsten Vaughan"
-  } ],
   "contactInformation" : {
     "telephoneNumber" : "+1 408 555 1212",
     "emailAddress" : "newuser@example.com"
@@ -188,8 +185,12 @@
   "userName" : "newuser@example.com",
   "displayName" : "New User",
   "meta" : {
-    "created" : "2013-03-26T10:44:26Z"
-  }
+    "created" : "2013-04-11T09:58:27Z"
+  },
+  "manager" : [ {
+    "_id" : "kvaughan",
+    "displayName" : "Kirsten Vaughan"
+  } ]
 }</screen>
    </listitem>
 
@@ -206,25 +207,31 @@
 
   <para>To read a resource, perform an HTTP GET.</para>
 
-  <screen>$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
+  <screen>$ curl
+ --request GET
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/newuser?_prettyPrint=true
 {
-  "_rev" : "00000000315fb731",
+  "_rev" : "000000005b337348",
   "schemas" : [ "urn:scim:schemas:core:1.0" ],
-  "manager" : [ {
-    "_id" : "trigden",
-    "displayName" : "Torrey Rigden"
-  } ],
   "contactInformation" : {
-    "telephoneNumber" : "+1 408 555 1862",
-    "emailAddress" : "bjensen@example.com"
+    "telephoneNumber" : "+1 408 555 1212",
+    "emailAddress" : "newuser@example.com"
   },
-  "_id" : "bjensen",
+  "_id" : "newuser",
   "name" : {
-    "familyName" : "Jensen",
-    "givenName" : "Barbara"
+    "familyName" : "New",
+    "givenName" : "User"
   },
-  "userName" : "bjensen@example.com",
-  "displayName" : "Barbara Jensen"
+  "userName" : "newuser@example.com",
+  "displayName" : "New User",
+  "meta" : {
+    "created" : "2013-04-11T09:58:27Z"
+  },
+  "manager" : [ {
+    "_id" : "kvaughan",
+    "displayName" : "Kirsten Vaughan"
+  } ]
 }</screen>
  </section>
 
@@ -237,7 +244,148 @@
  <section xml:id="delete-rest">
   <title>Deleting Resources</title>
 
-  <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-692</para>
+  <para>To delete a resource, perform an HTTP DELETE on the resource URL.
+  On success, the operation returns the resource you deleted.</para>
+
+  <screen>$ curl
+ --request DELETE
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/newuser?_prettyPrint=true
+{
+  "_rev" : "000000003a5f3cb2",
+  "schemas" : [ "urn:scim:schemas:core:1.0" ],
+  "contactInformation" : {
+    "telephoneNumber" : "+1 408 555 1212",
+    "emailAddress" : "newuser@example.com"
+  },
+  "_id" : "newuser",
+  "name" : {
+    "familyName" : "New",
+    "givenName" : "User"
+  },
+  "userName" : "newuser@example.com",
+  "displayName" : "New User",
+  "meta" : {
+    "created" : "2013-04-11T09:58:27Z"
+  },
+  "manager" : [ {
+    "_id" : "kvaughan",
+    "displayName" : "Kirsten Vaughan"
+  } ]
+}</screen>
+
+  <para>To delete a resource only if the resource matches a particular version,
+  use an <literal>If-Match: <replaceable>revision</replaceable></literal>
+  header.</para>
+
+  <screen>$ curl
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/newuser?_fields=_rev
+{"_rev":"000000006d8d7358"}
+$ curl
+ --request DELETE
+ --user kvaughan:bribery
+ --header "If-Match: 000000006d8d7358"
+ http://opendj.example.com:8080/users/newuser?_prettyPrint=true
+{
+  "_rev" : "00000000383f3cae",
+  "schemas" : [ "urn:scim:schemas:core:1.0" ],
+  "contactInformation" : {
+    "telephoneNumber" : "+1 408 555 1212",
+    "emailAddress" : "newuser@example.com"
+  },
+  "_id" : "newuser",
+  "name" : {
+    "familyName" : "New",
+    "givenName" : "User"
+  },
+  "userName" : "newuser@example.com",
+  "displayName" : "New User",
+  "meta" : {
+    "created" : "2013-04-11T12:48:48Z"
+  },
+  "manager" : [ {
+    "_id" : "kvaughan",
+    "displayName" : "Kirsten Vaughan"
+  } ]
+}</screen>
+
+  <orderedlist>
+   <para>To delete a resource and all its children, you must change the
+   configuration, get the REST LDAP gateway or HTTP Connection Handler to
+   reload its configuration, and perform the operation as a user who has the
+   access rights required. The following steps show one way to do this with
+   the HTTP Connection Handler.</para>
+
+   <para>In this case the LDAP view of the user to delete shows two child
+   entries.</para>
+
+   <screen>$ ldapsearch --port 1389 --baseDN uid=nbohr,ou=people,dc=example,dc=com "(&amp;)" dn
+dn: uid=nbohr,ou=People,dc=example,dc=com
+
+dn: cn=quantum dot,uid=nbohr,ou=People,dc=example,dc=com
+
+dn: cn=qubit generator,uid=nbohr,ou=People,dc=example,dc=com</screen>
+
+   <listitem>
+    <para>In the configuration file for the HTTP Connection Handler, by default
+    <filename>/path/to/OpenDJ/config/http-config.json</filename>, set
+    <literal>"useSubtreeDelete" : true</literal>.</para>
+
+    <note>
+     <para>After this change, only users who have access to request a tree
+     delete can delete resources.</para>
+    </note>
+   </listitem>
+
+   <listitem>
+    <para>Force the HTTP Connection Handler to reread its configuration.</para>
+
+    <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "HTTP Connection Handler"
+ <emphasis>--set enabled:false</emphasis>
+ --no-prompt
+$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "HTTP Connection Handler"
+ <emphasis>--set enabled:true</emphasis>
+ --no-prompt</screen>
+   </listitem>
+
+   <listitem>
+    <para>Delete as a user who has rights to perform a subtree delete on
+    the resource.</para>
+
+    <screen>$ curl
+ --request DELETE
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/nbohr?_prettyPrint=true
+{
+  "_rev" : "000000003d912113",
+  "schemas" : [ "urn:scim:schemas:core:1.0" ],
+  "contactInformation" : {
+    "telephoneNumber" : "+1 408 555 1212",
+    "emailAddress" : "nbohr@example.com"
+  },
+  "_id" : "nbohr",
+  "name" : {
+    "familyName" : "Bohr",
+    "givenName" : "Niels"
+  },
+  "userName" : "nbohr@example.com",
+  "displayName" : "Niels Bohr"
+}</screen>
+   </listitem>
+  </orderedlist>
  </section>
 
  <section xml:id="patch-rest">
@@ -261,6 +409,7 @@
   <para>TODO, fix pending https://bugster.forgerock.org/jira/browse/OPENDJ-775</para>
   <screen width="82">$ curl
  --request POST
+ --user kvaughan:bribery
  --header "Content-Type: application/json"
  --data '{
   "_id": "newuser",
@@ -282,12 +431,8 @@
  }'
  "http://opendj.example.com:8080/users?_action=create&amp;_prettyPrint=true"
 {
-  "_rev" : "00000000343b3ca6",
+  "_rev" : "0000000034a23ca7",
   "schemas" : [ "urn:scim:schemas:core:1.0" ],
-  "manager" : [ {
-    "_id" : "kvaughan",
-    "displayName" : "Kirsten Vaughan"
-  } ],
   "contactInformation" : {
     "telephoneNumber" : "+1 408 555 1212",
     "emailAddress" : "newuser@example.com"
@@ -300,8 +445,12 @@
   "userName" : "newuser@example.com",
   "displayName" : "New User",
   "meta" : {
-    "created" : "2013-03-26T10:52:42Z"
-  }
+    "created" : "2013-04-11T11:19:08Z"
+  },
+  "manager" : [ {
+    "_id" : "kvaughan",
+    "displayName" : "Kirsten Vaughan"
+  } ]
 }</screen>
 
   <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-695</para>
@@ -343,7 +492,7 @@
         <para>Matches when the pointer equals the value, as in the following
         example.</para>
 
-        <screen>$ curl 'http://opendj.example.com:8080
+        <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName+eq+"bjensen@example.com"&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -378,7 +527,7 @@
         <para>Matches when the pointer contains the value, as in the following
         example.</para>
 
-        <screen>$ curl 'http://opendj.example.com:8080
+        <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName+co+"jensen"&amp;_fields=userName&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -409,7 +558,7 @@
         <para>Matches when the pointer starts with the value, as in the
         following example.</para>
 
-        <screen>$ curl 'http://opendj.example.com:8080
+        <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName+sw+"ab"&amp;_fields=userName&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -430,7 +579,7 @@
         <para>Matches when the pointer is less than the value, as in the
         following example.</para>
 
-        <screen>$ curl 'http://opendj.example.com:8080
+        <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName+lt+"ac"&amp;_fields=userName&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -451,7 +600,7 @@
         <para>Matches when the pointer is less than or equal to the value, as
         in the following example.</para>
 
-        <screen>$ curl 'http://opendj.example.com:8080
+        <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName+le+"ad"&amp;_fields=userName&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -474,7 +623,7 @@
         <para>Matches when the pointer is greater than the value, as in the
         following example.</para>
 
-        <screen>$ curl 'http://opendj.example.com:8080
+        <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName+gt+"tt"&amp;_fields=userName&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -497,7 +646,7 @@
         <para>Matches when the pointer is greater than or equal to the value,
         as in the following example.</para>
 
-        <screen>$ curl 'http://opendj.example.com:8080
+        <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName+ge+"tw"&amp;_fields=userName&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -532,7 +681,7 @@
      any resource on which the <replaceable>json-pointer</replaceable> is
      present, as in the following example.</para>
 
-     <screen>$ curl 'http://opendj.example.com:8080
+     <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=userName%20pr&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -581,7 +730,7 @@
      <para>In other words you can list all resources in a collection as in the
      following example.</para>
 
-     <screen>$ curl 'http://opendj.example.com:8080
+     <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /groups?_queryFilter=true&amp;_fields=displayName&amp;_prettyPrint=true'
 {
   "result" : [ {
@@ -616,7 +765,7 @@
      nested inside the <literal>name</literal> and <literal>manager</literal>
      objects.</para>
 
-     <screen>$ curl 'http://opendj.example.com:8080
+     <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
  /users?_queryFilter=(userName+co+"jensen"+and+manager/displayName+sw+"Sam")
  &amp;_fields=displayName&amp;_prettyPrint=true'
 {
diff --git a/opendj3/src/site/resources/Example.ldif b/opendj3/src/site/resources/Example.ldif
index b026904..cbac340 100644
--- a/opendj3/src/site/resources/Example.ldif
+++ b/opendj3/src/site/resources/Example.ldif
@@ -20,7 +20,7 @@
 # CDDL HEADER END
 #
 #      Copyright 2006-2008 Sun Microsystems, Inc.
-#      Portions Copyright 2012 ForgeRock AS
+#      Portions Copyright 2012-2013 ForgeRock AS
 #
 #
 # dc=com sample LDIF file
@@ -66,11 +66,14 @@
  "userPassword")(version 3.0;acl "Anonymous read-search access";
  allow (read, search, compare)(userdn = "ldap:///anyone");)
 aci: (target="ldap:///dc=example,dc=com") (targetattr =
- "*")(version 3.0; acl "allow all Admin group"; allow(all) groupdn =
- "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
+ "*")(version 3.0; acl "allow all Admin group"; allow(all,export,import,proxy
+ ) groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
 aci: (target="ldap:///dc=example,dc=com") (targetattr ="*
  ")(version 3.0; acl "Allow apps proxied auth"; allow(all, proxy
  )(userdn = "ldap:///cn=*,ou=Apps,dc=example,dc=com");)
+aci: (targetcontrol="1.2.840.113556.1.4.805") (version 3.0; acl "
+ Tree delete for Admins"; allow(all) groupdn ="
+ ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
 
 dn: ou=Company Servers,dc=example,dc=com
 objectClass: organizationalUnit
@@ -3931,6 +3934,43 @@
 uidNumber: 1110
 gidNumber: 1000
 
+dn: uid=nbohr,ou=People,dc=example,dc=com
+objectClass: person
+#objectClass: cos
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: posixAccount
+objectClass: top
+uid: nbohr
+#classOfService: gold
+userpassword: password
+facsimileTelephoneNumber: +1 408 555 1213
+givenName: Niels
+cn: Niels Bohr
+telephoneNumber: +1 408 555 1212
+sn: Bohr
+roomNumber: 0007
+homeDirectory: /home/nbohr
+mail: nbohr@example.com
+l: San Francisco
+ou: People
+uidNumber: 1111
+gidNumber: 1000
+
+dn: cn=quantum dot,uid=nbohr,ou=People,dc=example,dc=com
+objectClass: device
+objectClass: top
+cn: quantum dot
+serialNumber: WI-3005
+owner: uid=nbohr,ou=People,dc=example,dc=com
+
+dn: cn=qubit generator,uid=nbohr,ou=People,dc=example,dc=com
+objectClass: device
+objectClass: top
+cn: qubit generator
+serialNumber: XF551426
+owner: uid=nbohr,ou=People,dc=example,dc=com
+
 # Quotas by class of service
 dn: cn=Bronze Class of Service,dc=example,dc=com
 objectClass: collectiveAttributeSubentry

--
Gitblit v1.10.0