cmis 0.1.0-java → 0.2.0-java

data/README.md

@@ -42,6 +42,8 @@ server is http://cmis.alfresco.com/cmisatom.
 
 Nuxeo also provides a demo server. More information can be found here: http://doc.nuxeo.com/display/NXDOC/CMIS+for+Nuxeo#CMISforNuxeo-Onlinedemo .
 
+The documentation below is heavily based on the [OpenCMIS Client API Developer's Guide](http://chemistry.apache.org/java/developing/guide.html)
+
 ## Connecting to a CMIS repository
 
 To be able to do anything useful on a CMIS repository, you must first find a repository, and create a session with it:
@@ -123,6 +125,8 @@ doc.download(file)
 
 ### Updating a document
 
+Updating metadata:
+
 ```ruby
 id = root.create_cmis_document("cmis_logo_original.png", "/Users/ricn/cmis_logo.png")
 doc = @session.get_object(id)
@@ -133,6 +137,27 @@ doc = @session.get_object(id)
 puts "New name: #{doc.name}"
 ```
 
+Updating the actual content of a document (using check out / check in):
+```ruby
+root = @session.root_folder
+doc = root.create_text_doc("my_file.txt", "content")
+puts "Orginal version: " + doc.version_label
+id = doc.check_out
+working_copy = @session.get_object(id)
+
+content_stream = CMIS::create_content_stream("/Users/ricn/updated_file.txt", @session)
+
+# check_in parameters: boolean major, properties, contentStream, checkinComment
+id = working_copy.check_in(false, nil, content_stream, "minor version")
+doc = @session.get_object(id)
+
+puts "New version: " + doc.version_label
+```
+
+Update the content of a document directly:
+
+TODO
+
 ### Deleting a document
 
 ```ruby
@@ -147,8 +172,9 @@ doc.delete # Yay, that was easy!
 folder1 = root.create_cmis_folder("folder1")
 folder11 = folder1.create_cmis_folder("Folder11")
 folder12 = folder1.create_cmis_folder("Folder12")
-# Delete it
-folder1.delete_tree(true, CMIS::UnfileObject::DELETE, true) # parameter explanation: boolean allversions, UnfileObject unfile, boolean continueOnFailure
+
+# Parameter: boolean allversions, UnfileObject unfile, boolean continueOnFailure
+folder1.delete_tree(true, CMIS::UnfileObject::DELETE, true)
 ```
 
 ## Working with CMIS Properties
@@ -183,25 +209,234 @@ puts "Content stream file name: " + doc.content_stream_file_name
 puts "Content stream mime type: " + doc.content_stream_mime_type
 ```
 
+Get allowed actions for a document or folder:
+
+```ruby
+root = @session.root_folder
+allowed_actions = root.allowed_actions
+
+allowed_actions.each do |a|
+  puts a.to_s + " is an allowed action on " + root.name
+end
+```
+
+A complete list of actions can be found here: http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/commons/enums/Action.html
+
 ## Working with CMIS Queries
 
 ```ruby
-query = "SELECT * FROM cmis:document WHERE cmis:name LIKE 'cmis%'"
-q = @session.query(query, false) # true means search all versions
+query = "SELECT * FROM cmis:folder"
+q = @session.query(query, false) # false means only latest versions
 
 q.each do |result|
-  puts result.property_value_by_query_name("cmis:name")
+  props = result.properties
+  props.each do |p|
+    disp_name = p.display_name
+    puts "Name: " + p.first_value if disp_name == "Name"
+  end
 end
 ```
 
-## DOCUMENTION TODO:
-* Add Multi-filing and Unfiling examples
-* Add Relationships examples
-* Add Access control examples
-* Add OperationContext examples
-* Add Advanced types usage examples
-* Add Performance notes
-* Add Troubleshooting notes
+## Capabilities
+CMIS repositories has different capabilities. Some are designed for a specific application domain and do not provide capabilities that are not needed for that domain. This means a repository implementation may not be able to support all the capabilities that the CMIS specification provides. To allow this, some capabilities can be optionally supported by a CMIS repository.
+
+This is how you check the capabilites of the repository:
+
+```ruby
+rep_info = @session.repository_info
+cap = rep_info.capabilities
+
+puts "Navigation Capabilities"
+puts "Get descendants supported: " + cap.is_get_descendants_supported.to_s
+puts "Get folder tree supported: " + cap.is_get_folder_tree_supported.to_s
+puts "=============================="
+puts "Object Capabilities"
+puts "Content Stream: " + cap.content_stream_updates_capability.value
+puts "Changes: " + cap.changes_capability.value
+puts "Renditions: " + cap.renditions_capability.value 
+puts "=============================="
+puts "Filing Capabilities"
+puts "Multifiling supported: " + cap.is_multifiling_supported.to_s
+puts "Unfiling supported: " + cap.is_unfiling_supported.to_s
+puts "Version specific filing supported: " + cap.is_version_specific_filing_supported.to_s
+puts "=============================="
+puts "Versioning Capabilities"
+puts "PWC searchable: " + cap.is_pwc_searchable_supported.to_s
+puts "PWC updatable: " + cap.is_pwc_updatable_supported.to_s
+puts "All versions searchable: " + cap.is_all_versions_searchable_supported.to_s
+puts "=============================="
+puts "Query Capabilities"
+puts "Query: " + cap.query_capability.value
+puts "Join: " + cap.join_capability.value
+puts "=============================="
+puts "ACL Capabilities"
+puts "ACL: " + cap.acl_capability.value
+```
+
+## Paging
+When you retrieve the children of a CMIS object, the result set returned is of an arbitrary size. Retrieving a large result set synchronously could increase response times. To improve performance, you can use OpenCMIS's paging support to control the size of the result set retrieved from the repository. To use paging, 
+you must specify an [OperationContext](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/OperationContext.html) when invoking children method call on the parent object. The OperationContext specifies the maximum number of items to retrieve in a page.
+
+```ruby
+root = @session.root_folder
+oc = CMIS::OperationContextImpl.new
+oc.max_items_per_page = 3
+
+# List all object in the root folder using paging
+page1 = root.children(oc).skip_to(0).page.map(&:name)
+page2 = root.children(oc).skip_to(1).page.map(&:name)
+
+puts "Page 1:"
+page1.each do |o|
+  puts o
+end
+
+puts "Page 2:"
+page2.each do |o|
+  puts o
+end
+```
+
+## Renditions
+
+Some repositories provide a facility to retrieve alternative representations, or renditions of a document. An example is a preview thumbnail image of the content of a document, which could be presented to the user without needing to download the full document content. Another example is a PDF version of a word document.
+
+A CMIS repository may have zero or more renditions for a document or folder in addition to the document's content stream.
+At present the CMIS specification only allows renditions to be read. There are no facilities to create, update or delete renditions. Renditions are of a specific version of the document and may differ between document versions. Each rendition consists of a set of rendition attributes and a rendition stream. Rendition attributes are not object properties, and are not queryable. Renditions can be retrieved using the getRenditions service.
+
+```ruby
+puts "Rendition support: " + @session.repository_info.capabilities.renditions_capability.to_s
+
+id = @session.root_folder.create_text_doc("simple file.txt", "My content")
+context = @session.create_operation_context
+context.rendition_filter_string = "cmis:thumbnail"
+doc = @session.get_object(id, context)
+
+renditions = doc.renditions
+
+puts "Renditions"
+renditions.each do |r|
+  puts "Kind" + r.kind
+  puts "Mimetype: " + r.mime_type
+end
+```
+
+Note: If you run the code above you might not get the renditions directly. Many repositories renders them asynchronously so it will take some time before you see them.
+
+## Multi-filing
+Multi-filing allows you to file a document object in more than one folder. This capability are optional, and your repository may not support them.
+
+```ruby
+doc = @session.root_folder.create_text_doc("Multi-filing.txt", "Content")
+folder = @session.root_folder.create_cmis_folder("multi-filing")
+puts "Document parent count: " + doc.parents.size.to_s
+doc.add_to_folder(folder, true) # true means all versions
+puts "Document parent count: " + doc.parents.size.to_s
+```
+
+## Access control
+
+Document or folder objects can have an access control list (ACL), which controls access to the object. An ACL is a list of Access Control Entries (ACEs). An ACE grants one or more permissions to a principal. A principal is a user, group, role, or something similar.
+
+An ACE contains:
+* One String with the principalid
+* One or more Strings with the names of the permissions.
+* A boolean flag direct, which is true if the ACE is directly assigned to the object, or false if the ACE is somehow derived
+
+There are three basic permissions predefined by CMIS:
+* cmis:read: permission for reading properties and reading content
+* cmis:write: permission to write properties and the content of an object. A respository can defin the property to include cmis:read
+* cmis:all: all the permissions of a repository. It includes all other basic CMIS permissions.
+
+How these basic permissions are mapped to allowable actions is repository specific. You can discover the repository semantics for basic permissions with regard to allowable actions by examining the mappings parameter returned by session method repository_info. A repository can extend the basic permissions with its own repository-specific permissions. The folowing code snippet prints out the permissions available for a repository, 
+and the mappings of allowable actions to repository permissions:
+
+```ruby
+acl_caps = @session.repository_info.acl_capabilities
+
+puts "Propogation for this repository is " + acl_caps.acl_propagation.to_s
+
+puts "Permissions for this repository are: "
+acl_caps.permissions.each do |p|
+  puts "ID: " + p.id + " description: " + p.description 
+end
+
+puts "Permission mappings for this repository are:"
+repo_mapping = acl_caps.permission_mapping
+
+repo_mapping.each do |key, value|
+  puts key + " maps to " + repo_mapping.get(key).permissions.to_s
+end
+```
+
+You can specify how a repository should handle non-direct ACEs when you create an ACL, by specifying one of the following acl propogation values:
+
+* OBJECTONLY: apply ACEs to a document or folder, without changing the ACLs of other objects
+* PROPAGATE: apply ACEs to the given object and all inheriting objects
+* REPOSITORYDETERMINED: allow the repository to use its own method of computing how changing an ACL for an object influences the non-direct ACEs of other objects.
+
+The following example creates a folder object, and prints out the ACEs in the created folder's ACL. It then creates a new ACL with one ACE, adds it to the folder, retrieves the folder again, and prints out the ACEs now present in the folder's ACL:
+
+```ruby
+folder = @session.root_folder.create_cmis_folder("ACL test")
+oc = CMIS::OperationContextImpl.new
+oc.include_acls = true 
+folder = @session.get_object(folder, oc)
+
+aces = folder.acl.aces
+puts "Permissions before we add the guest user:"
+aces.each do |a|
+  puts "Principal: " + a.principal.id
+  a.permissions.each do |p|
+    puts "Permission ID: " + p
+  end
+end
+
+permissions = ["cmis:read"]
+principal = "guest" # Built in user in Alfresco
+ace_in = @session.object_factory.create_ace(principal, permissions)
+folder.add_acl([ace_in], CMIS::AclPropagation::REPOSITORYDETERMINED)
+folder = @session.get_object(folder, oc)
+
+aces = aces = folder.acl.aces
+puts "Permissions after we added the guest user:"
+aces.each do |a|
+  puts "Principal: " + a.principal.id
+  a.permissions.each do |p|
+    puts "Permission ID: " + p
+  end
+end
+```
+
+## Relationships
+
+A Relationship object is a relationship between a source object and a target object. The relationship has direction, from source to target. It is non-invasive, in that a relationship does not modify either the source or the target object. A relationship object has a type, like any other CMIS object. The source and target objects must be independent objects, such as a document, folder, or policy objects. A relationship object does not have a content-stream, and is not versionable, queryable, or fileable.
+
+A repository does not have to support relationships. If it doesn't the relationship base object-type will not be returned by a "get types" call.
+
+The following example creates a relationship between 2 objects. Alfresco supports relationships, but the base type cmis:relationship is not defined as creatable, so the example uses an existing type R:cmiscustom:assoc which is a creatable sub-type of cmis:relationship in Alfresco:
+
+```ruby
+content_stream = CMIS::create_content_stream("/Users/ricn/source.txt", @session)
+source_props = { CMIS::PropertyIds::OBJECT_TYPE_ID => "D:cmiscustom:document", CMIS::PropertyIds::NAME => "source.txt" }
+source_doc = @session.root_folder.create_document(source_props, content_stream, CMIS::VersioningState::MAJOR)
+
+content_stream = CMIS::create_content_stream("/Users/ricn/target.txt", @session)
+target_props = { CMIS::PropertyIds::OBJECT_TYPE_ID => "D:cmiscustom:document", CMIS::PropertyIds::NAME => "target.txt" }
+target_doc = @session.root_folder.create_document(target_props, content_stream, CMIS::VersioningState::MAJOR)
+        
+rel_props = {
+  "cmis:sourceId" => source_doc.id, 
+  "cmis:targetId" => target_doc.id, 
+  "cmis:objectTypeId" => "R:cmiscustom:assoc"
+}
+
+rel = @session.create_relationship(rel_props)
+rel = @session.get_object(rel)
+
+puts rel.source.id
+puts rel.target.id
+```
 
 ## Contributing
 

data/lib/cmis.rb

@@ -17,8 +17,10 @@ module CMIS
   import org.apache.chemistry.opencmis.commons.SessionParameter
   import org.apache.chemistry.opencmis.commons.PropertyIds
   import org.apache.chemistry.opencmis.commons.impl.MimeTypes
+  import org.apache.chemistry.opencmis.commons.data.AclCapabilities
   
   import org.apache.chemistry.opencmis.commons.enums.Action
+  import org.apache.chemistry.opencmis.commons.enums.AclPropagation
   import org.apache.chemistry.opencmis.commons.enums.BaseTypeId
   import org.apache.chemistry.opencmis.commons.enums.CapabilityAcl
   import org.apache.chemistry.opencmis.commons.enums.VersioningState
@@ -49,6 +51,10 @@ module CMIS
     def download(destination_path)
       FileUtils.download(self, destination_path)
     end
+
+    def allowed_actions
+      self.allowable_actions.allowable_actions.to_a
+    end
   end
   
   class FolderImpl
@@ -72,6 +78,10 @@ module CMIS
     def create_text_doc(name, content)
       FileUtils.create_text_document(self.id, name, content, "cmis:document", CMIS::VersioningState::MAJOR, session)
     end
+
+    def allowed_actions
+      self.allowable_actions.allowable_actions.to_a
+    end
   end
 
   def self.create_session(url, user, password, repo_id = nil)

data/lib/cmis/version.rb

@@ -1,3 +1,3 @@
 module Cmis
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/spec/cmis_spec.rb

@@ -79,6 +79,16 @@ describe "CMIS" do
         allowed_actions.to_a.should include(CMIS::Action::CAN_GET_PROPERTIES)
       end
 
+      it "should retrieve allowed actions for an object using convenient method" do
+        # for a folder
+        allowed_actions = @session.root_folder.allowed_actions
+        allowed_actions.should include(CMIS::Action::CAN_GET_PROPERTIES)
+
+        doc = create_random_doc(@test_folder)
+        allowed_actions = doc.allowed_actions
+        allowed_actions.should include(CMIS::Action::CAN_GET_PROPERTIES)
+      end
+
       it "should be possible to check if a document is versionable" do
         doc = create_random_doc(@test_folder)
         doc.type.is_versionable.should == true
@@ -158,6 +168,13 @@ describe "CMIS" do
           p.value.should == content.size if p.definition.id == "cmis:contentStreamLength"
         end
       end
+
+      it "should be possible to use multi-filing" do
+        doc = create_random_doc(@test_folder)
+        folder = @test_folder.create_cmis_folder("multi-filing")
+        doc.add_to_folder(folder, true) # true means all versions
+        doc.parents.size.should == 2
+      end
     end
 
     describe "Updating objects" do
@@ -246,6 +263,46 @@ describe "CMIS" do
         @sub_folder.children.map(&:name).size.should == 5
       end
     end
+
+    describe "Access control" do
+      it "should be possible to add acls to an object" do
+        folder = @test_folder.create_cmis_folder("ACL test")
+        oc = CMIS::OperationContextImpl.new
+        oc.include_acls = true 
+        folder = @session.get_object(folder, oc)
+        original_acl_size = folder.acl.aces.size
+        
+        permissions = ["cmis:read"]
+        principal = "guest"
+        ace_in = @session.object_factory.create_ace(principal, permissions)
+        folder.add_acl([ace_in], CMIS::AclPropagation::REPOSITORYDETERMINED)
+        folder = @session.get_object(folder, oc)
+        folder.acl.aces.size.should == original_acl_size + 2
+      end
+    end
+
+    describe "Relationships" do
+
+      it "should be possible to create relationships" do
+        content_stream = CMIS::create_content_stream(file_path("text_file.txt"), @session)
+        source_props = { CMIS::PropertyIds::OBJECT_TYPE_ID => "D:cmiscustom:document", CMIS::PropertyIds::NAME => "source.txt" }
+        source_doc = @test_folder.create_document(source_props, content_stream, CMIS::VersioningState::MAJOR)
+        
+        target_props = { CMIS::PropertyIds::OBJECT_TYPE_ID => "D:cmiscustom:document", CMIS::PropertyIds::NAME => "target.txt" }
+        target_doc = @test_folder.create_document(target_props, content_stream, CMIS::VersioningState::MAJOR)
+        
+        rel_props = {
+          "cmis:sourceId" => source_doc.id, 
+          "cmis:targetId" => target_doc.id, 
+          "cmis:objectTypeId" => "R:cmiscustom:assoc"
+        }
+
+        rel = @session.create_relationship(rel_props)
+        rel = @session.get_object(rel)
+        rel.source.id.should == source_doc.id
+        rel.target.id.should == target_doc.id
+      end   
+    end
   end
 
   describe "Local Alfresco" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmis
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease:
 platform: java
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-01-28 00:00:00.000000000 Z
+date: 2013-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec