Monday, February 9, 2009

Aspects

Aspects are a mechanism for adding behavior and/or state to a Documentum object instance without changing its base type. They are similar to TBOs, but they are not associated with any one document type. Aspects also are late bound rather than early bound objects, so they can be added to an object or removed as needed. Aspect is defined as [attributes] + [behavior]. Aspects are a BOF type (dmc_aspect_type). Like other BOF types, they have the characteristics: • Aspects are installed into a repository. • Aspects are downloaded on demand and cached on the local file system. • When the code changes in the repository, aspects are automatically detected and new code is “hot deployed” to the DFC runtime.

8.1 Characteristics of Aspects

  • Client attaches an aspect to an object instance.
  • A persistent object may have multiple uniquely named aspects with or without attributes.
  • Different object instances of the same persistent type may have different sets of aspects.
  • Customization-specific metadata associated with an object - Aspects define the metadata and set values
  • No restriction on the nature of metadata that an aspect can define - Single or repeating, any supported data type
  • Syntax to define the metadata is close to defining an object type.
  • An aspect with attribute definition can be attached to object of any type-provides a natural extension to the base type.
  • Attributes defined by one aspect can be accessed by others.

 

8.2 Aspects Usage

An aspect is a very useful business concept as it is not depend on a specific object type. Let‟s consider an application of an organization. “Organization has various departments and each department has it own set of document, lifecycles and approval workflow model. Now it is required that every object in the repository must be tagged to an organization. Also, there could be some objects which may not belong to organization but are referred for various purposes. It may be possible that each document has a specific behavior according to the organization it belongs to and after some time an object may become obsolete and may not be held by an organization.” In this type of situation an aspect is a very useful concept as it is applied to the object instance and not on the object type. Since aspect has its own attributes it is not required to define the attributes for the object types. Also aspect has its own behavior. Aspect can be detached at any point of time. Also, if the application demands, at any point of time any number of aspects can be attached to the document. It is also possible to add/remove attributes in aspects through DQL. Aspect attributes can be queried as other attributes. One aspect when attached to an object can not be reattached to the object. In these type of cases either modify the aspect properties through DQL or detach the aspect and reattach it. Aspects can also be called from TBO.

8.3 Aspect Implementation

Aspect are implemented through DFC API com.documentum.fc.client.aspect.IDfAspects Code:

[Reference :DFC guide] For example, you might have objects that represent customer contact records. When a contact becomes a customer, you could attach an aspect that encapsulates the additional information required to provide customer support. This way, the system won‟t be burdened with maintenance of empty fields for the much larger set of prospective customers. Another scenario might center around document retention. For example, your company might have requirements for retaining certain legal documents (contracts, invoices, schematics) for a specific period of time. You can attach an aspect that will record the date the document was created and the length of time the document will have to be retained. This way, you are able to attach the retention aspect to documents regardless of object type, and only to those documents that have retention requirements.

Creating an aspect Aspects are created in a similar fashion to other BOF modules.

1. Decide what your aspect will provide: behavior, attributes, or both.

2. Create the interface and implementation classes

3. Deploy the aspect module Aspect can be deployed through Composer.

Composer is a tool provided by EMC which builds and installs Docapps. For deployment refer to Composer User Guide. Creating the aspect interface Define the new behavior for your aspect in an interface. In this case, we‟ll add getters and setters for two attributes: service_level and expiration_date.

package com.miti.asset2; import com.documentum.fc.common.DfException; import com.documentum.fc.common.IDfTime; public interface ICustomerAspect{ // Behavior for extending the expiration date by <i>n</i> months. public String extendExpirationDate(int months) throws DfException; // Getters and setters for custom attributes. public abstract IDfTime getExpirationDate() throws DfException; public abstract String getServiceLevel() throws DfException; public abstract void setExpirationDate(IDfTime expirationDate) throws DfException; public abstract void setServiceLevel(String level) throws DfException; } Creating the aspect class Now that we have our interface, we can implement it with a custom class. It is necessary to implement IDfModule as Composer wont build the aspect otherwise, though DFC guide has not implemented it. package com.miti.asset2; import com.documentum.fc.client.DfDocument; import com.documentum.fc.client.IDfModule; import com.documentum.fc.common.DfException; import com.documentum.fc.common.DfTime; import com.documentum.fc.common.IDfTime; import java.util.GregorianCalendar;
public class CustomerAspect extends DfDocument implements ICustomerAspect,IDfModule{ public String extendExpirationDate(int months) { try { //Get the current expiration date. IDfTime startDate = getExpirationDate(); //Convert the expiration date to a calendar object. GregorianCalendar cal = new GregorianCalendar(startDate.getYear(), startDate.getMonth(),startDate.getDay()); //Add the number of months 1(months start counting from 0). cal.add(GregorianCalendar.MONTH,months-1) ; //Convert the recalculated date to a DfTime object. IDfTime endDate = new DfTime (cal.getTime()); //Set the expiration date and return results. setExpirationDate(endDate); return "New expiration date is " + endDate.toString(); } catch (Exception ex) { ex.printStackTrace(); return "Exception thrown: " + ex.toString(); } } //Getters and setters for the expiration_date and service_level custom attributes. public IDfTime getExpirationDate() throws DfException { return getTime("aspecttrial.expiration_date"); } public String getServiceLevel() throws DfException { return getString("aspecttrial.service_level"); } public void setExpirationDate(IDfTime expirationDate) throws DfException { setTime("aspecttrial.expiration_date", expirationDate); } public void setServiceLevel (String serviceLevel) throws DfException { setString("aspecttrial.service_level", serviceLevel); } } TestCustomerServiceAspect Once you have compiled and deployed your aspect classes and defined the aspect on the server, you can use the class to set and get values in the custom aspect, and to test the behavior for adjusting the expiration date by month. package com.miti.aspect; import com.miti.asset2.ICustomerAspect; import com.documentum.com.DfClientX; import com.documentum.com.IDfClientX; import com.documentum.fc.client.IDfDocument; import com.documentum.fc.client.IDfSession; import com.documentum.fc.client.aspect.IDfAspects; import com.documentum.fc.common.DfException;
import com.documentum.fc.common.DfId; import com.documentum.fc.common.DfTime; import com.documentum.fc.common.IDfList; import com.documentum.fc.common.IDfTime; public class TestCustomerAspect{ public TestCustomerAspect() { } public static String attachCustomerAspect(IDfSession mySession,String docId,String serviceLevel,String expirationDate){ //Instantiate a client. IDfClientX clientx = new DfClientX(); try { String result = ""; //Get the document instance using the document ID. IDfDocument doc =(IDfDocument) mySession.getObject(new DfId(docId)); //Convert the expirationDate string to an IDfTime object. //DF_TIME_PATTERN1 is "mm/dd/yy" IDfTime ed =clientx.getTime(expirationDate,DfTime.DF_TIME_PATTERN1); //Attach the aspect. ((IDfAspects)doc).attachAspect("aspecttrial",null); //Save the document. doc.save(); //Get the document with its newly attached aspect. doc = (IDfDocument)mySession.getObject(doc.getObjectId()); //Set the aspect values. doc.setString("aspecttrial.service_level",serviceLevel); doc.setTime("aspecttrial.expiration_date", ed); //Save the document. doc.save(); result = "Document " + doc.getObjectName() +" set to service level " +doc.getString("aspecttrial.service_level") +" and will expire " +doc.getTime("aspecttrial.expiration_date").toString()+"."; return result; } catch (Exception ex) { ex.printStackTrace(); return "Exception thrown:" + ex.toString(); } } public String extendExpirationDate(IDfSession mySession,String docId,int months) { //Instantiate a client. IDfClientX clientx = new DfClientX(); try { String result = ""; //Get the document instance using the document ID. IDfDocument doc =(IDfDocument) mySession.getObject(new DfId(docId)); //Call the extendExpirationDate method result = ((ICustomerAspect)doc).extendExpirationDate(months); //Save the document. doc.save(); return result;
} catch (Exception ex) { ex.printStackTrace(); return "Exception thrown."; } } public String setExpirationDate(IDfSession mySession,String docId,String expDate) { // Instantiate a client. IDfClientX clientx = new DfClientX(); try { String result = ""; IDfTime expirationDate = clientx.getTime( expDate, IDfTime.DF_TIME_PATTERN1 ); //Get the document instance using the document ID. IDfDocument doc = (IDfDocument) mySession.getObject(new DfId(docId)); //Set the date using the time object. doc.setTime("aspecttrial.expiration_date",expirationDate); //Save the document and return the result. doc.save(); result = "Expiration date set to " +doc.getTime("aspecttrial.expiration_date").toString(); return result; } catch (Exception ex) { ex.printStackTrace(); return "Exception thrown."; } } public String setServiceLevel(IDfSession mySession,String docId,String serviceLevel){ String result = ""; //Instantiate a client. IDfClientX clientx = new DfClientX(); try { //Get the document instance using the document ID. IDfDocument doc =(IDfDocument) mySession.getObject(new DfId(docId)); //Set the date using the time object. doc.setString("aspecttrial.service_level",serviceLevel); //Save the document. doc.save(); result = "Service Level set to " +doc.getString("aspecttrial.service_level")+ "."; return result; } catch (Exception ex) { ex.printStackTrace(); return "Exception thrown."; } } public static String getServiceLevel(IDfSession mySession,String docId){
String lsName=null; try { IDfDocument loDoc=(IDfDocument)mySession.getObject(new DfId(docId)); IDfList loIdfList=((IDfAspects)loDoc).getAspects(); System.out.println("aspect Name"+(loIdfList.getString(0))); lsName=loDoc.getString("aspecttrial.service_level"); } catch (DfException e) { // TODO Auto-generated catch block e.printStackTrace(); } return lsName; } } Call Aspect Now attach the aspect to an object. Here we have call the method of TestCustomerAspect described above to attach an aspect to a document. package com.miti.aspect; import com.documentum.com.DfClientX; import com.documentum.com.IDfClientX; import com.documentum.fc.client.IDfClient; import com.documentum.fc.client.IDfSession; import com.documentum.fc.client.IDfSessionManager; import com.documentum.fc.client.IDfSysObject; import com.documentum.fc.common.DfException; import com.documentum.fc.common.IDfId; import com.documentum.fc.common.IDfLoginInfo; public class testDfc{ public static void main(String args[]){ try{ IDfClientX loidfClientx=new DfClientX(); IDfClient loidfClient =loidfClientx.getLocalClient(); IDfLoginInfo loIdfLogin=loidfClientx.getLoginInfo(); loIdfLogin.setUser("user"); loIdfLogin.setPassword("password"); loIdfLogin.setDomain(null); IDfSessionManager loIdfSessionMgr= loidfClient.newSessionManager(); loIdfSessionMgr.setIdentity("repository", loIdfLogin); IDfSession loIDFSession=loIdfSessionMgr.getSession("repository"); System.out.println(loIDFSession.toString()); String qualification = "my_doc where object_name='reviewer_dmDoc'"; IDfSysObject idfSysobject = (IDfSysObject)loIDFSession.getObjectByQualification( qualification ); IDfId idfID=idfSysobject.getObjectId(); System.out.println("2"+idfID.toString()); TestCustomerAspect.attachCustomerAspect(loIDFSession,idfID.toString(),"gold","02/02/2008"); System.out.println("attached");
String lsName=TestCustomerAspect.getServiceLevel(loIDFSession,idfID.toString()); System.out.println("Service level"+lsName); System.out.println(lsName); }catch(DfException loDfexc){ loDfexc.printStackTrace(); } } } Console Output
8.4 DQL WITH Aspects
Add Attributes ALTER ASPECT aspect_name_ ADD attribute_def[,attribute_def][OPTIMIZEFETCH| NO OPTIMIZEFETCH] [PUBLISH] Drop Attributes ALTER ASPECT aspect_name DROP attribute_name[, attribute_name] [PUBLISH] ALTER ASPECT aspect_name DROP ALL [PUBLISH] The OPTIMIZEFETCH keyword in the ALTER ASPECT statement causes the aspect attribute values to be stored alongside the object to which the aspect is attached. This results in reduced database queries and can improve performance. The aspect attributes are duplicated into the object’s property bag. Select Attributes Select r_object_id,object_name,aspecttrial.service_level from dm_document where object_name like ‘reviewe%’
DQL Results Aspect attributes are mentioned as ‘aspectname.attributename’ ADD Fulltext index ALTER ASPECT aspect_name FULLTEXT SUPPORT ADD | DROP a1, a2,... Note: The query given in DQL guide for fulltext on aspects does not update the object. Correct query is mentioned in DFC guide as given above. Enabling aspects on object types By default, dm_sysobject and its subtypes are enabled for aspects. This includes any custom object sub types. Any non sysobject application type can be enabled for use with aspects using the following syntax. ALTER TYPE type_name ALLOW ASPECTS Aspect in Webtop Currently there is no provision of viewing aspect attributes in webtop. Only option ab=vailable is to customize the component.

No comments:

Post a Comment