Difference between revisions of "Stardust/Knowledge Base/Java API/Document Security"

Revision as of 06:39, 14 March 2012

Overview:

The Stardust comes with built in Apache’s Jackrabbit, an open source JCR implementation. Stardust provides a service, called Document Management Service (DMS), to integrate with the JCR. Apart from document CRUD, it integrates well with Stardust users, roles, departments, and process attachments seamlessly.

In this article, we will see basic document security API features provided by the Stardust. Admin can control the security settings using document repository view of the Stardust portal. For detail, refer “Infinity Documentation > End User Handbooks > Infinity Portal > Common Detail Views and Dialogs > Access Control Editor” section of the product documentation at https://infinity.sungard.com/documentation/ipp/6.0/index.jsp

Enabling Document Security:

Document security is not enabled by default. Refer the product documentation mentioned above for enabling document security.

Document Management Service:

This service, DMS, provides basic API for documents and its security management. Apart from providing features to create, read, update, and delete documents and folders, it enables retrival and updation of the document security data.

The DMS service methods, getPolicies() and getApplicablePolicies(), are used to fetch the existing document security policies. Whereas, setPolicy() method is used to update the document security data.

Next, we will see security API data structure and how we can read and update the security data associated with the documents.

Security Data Structure:

A document has set of AccessControlPolicy objects containing security permissions associated with it. Each AccessControlPolicy has a set of AccessControlEntry objects. Where, a signle AccessControlEntry object represents a principal along with its security fields, called privileges.

A principal can be any model participant or dynamic/runtime entity like user or department. The set of privileges can contain all or subset of security permissions given below.

Document ACL Security Permissions/Fields:

The document security has the following six fields:

• Create
• Read
• Modify
• Delete
• Read ACL
• Modify ACL

ACL stands for Access Control List. All of these fields can have value of “Allow” or “Deny” to indicate the corresponding permissions. These fields are editable per participant. Any number of available participants can be added on the document ACL along with their respective permisions. and thus their security permissions can be edited separately.

Reading the Document Security:

The following code snippet shows how to read the security data associated with the sample document;

...
 
              DocumentManagementService dms = sf.getDocumentManagementService();
		List<Document> documentsByName = dms
				.findDocumentsByName("testfile.txt");
 
		if (documentsByName != null && !documentsByName.isEmpty()) {
			for (Document doc : documentsByName) {
				Set<AccessControlPolicy> policies = dms
						.getPolicies(doc.getId());
				Set<AccessControlPolicy> aPolicies = dms
						.getApplicablePolicies(doc.getId());
 
				for (AccessControlPolicy accessControlPolicy : policies) {
					Set<AccessControlEntry> accessControlEntries = accessControlPolicy
							.getAccessControlEntries();
					for (AccessControlEntry accessControlEntry : accessControlEntries) {
						System.out.println("accessControlEntry.getPrincipal():"
								+ accessControlEntry.getPrincipal());
						System.out
								.println("accessControlEntry.getPrivileges():"
										+ accessControlEntry.getPrivileges());
					}
				}				
			}
		} else {
			throw new RuntimeException("Document not found exception:-(");
		}

int test;

Updating the Document Security:

The following code snippet shows how to update security data associated with the sample document. Note the usage of DmsPrincipal and DmsPrivilege. These objects are used while adding new AccessControlEntry in the document's existing AccessControlPolicy instance.

...
	      DocumentManagementService dms = sf.getDocumentManagementService();
		List<Document> documentsByName = dms
				.findDocumentsByName("testfile.txt");
 
		if (documentsByName != null && !documentsByName.isEmpty()) {
			for (Document doc : documentsByName) {
				Set<AccessControlPolicy> policies = dms
						.getPolicies(doc.getId());
 
				// Add the Employee role to read and edit this doc
 
				Principal emp = new DmsPrincipal("Employee"); 
                                   // 'Employee' is a role id.
				// Here instead of this DmsPrincipal constructor use
				// DmsPrincipal(ModelParticipantIndo...)
 
				Set<Privilege> privileges = new HashSet<Privilege>();
				privileges.add(DmsPrivilege.READ_PRIVILEGE);
				privileges.add(DmsPrivilege.MODIFY_PRIVILEGE);
 
				AccessControlPolicy next = null;
				try {
					policies = dms.getPolicies(doc.getId());
					next = policies.iterator().next();
				} catch (java.util.NoSuchElementException nee) {
					policies = dms.getApplicablePolicies(doc.getId());
					next = policies.iterator().next();
 
				}
				next.addAccessControlEntry(emp, privileges);
				dms.setPolicy(doc.getId(), next);
 
			}
		} else {
			throw new RuntimeException("Document not found exception:-(");
		}