Introduction to the WDK Datagrid - EMC Community Network

Documentum DFS, UCF and ASP .NET – Practical GuideBy Mirza Fazlic, August 2009 – mirza.fazlic@gmail.comThis article is a practical guide to the use of UCF as a content transfer mechanism in a DFS basedapplication. For theory behind UCF, please consult the DFS documentation. The example DFSapplication demonstrated in this article will be built using a custom UCF Applet integrated with anASP .NET application. Core services for view, upload, checkout and check in will be covered. Youshould be familiar with the basic DFS concepts. This article was written using DFS 6.5 SP1.INTRODUCTION .....................................................................................................................................2APPLICATION OVERVIEW ....................................................................................................................2ENVIRONMENT OVERVIEW ..................................................................................................................3UCF APPLET ..........................................................................................................................................3Including the applet in the ASP .NET page .......................................................................................................................3Applet security requirements .............................................................................................................................................4Creating a keystore ...........................................................................................................................................................4Signing the applet jar file ...................................................................................................................................................4Applet Code .........................................................................................................................................................................5Building the applet .............................................................................................................................................................6UCF Client Installer Process ...............................................................................................................................................7ASP .NET APPLICATION .....................................................................................................................10Document Listing Component .........................................................................................................................................10Page PostBack and Browser Refresh Problem ..............................................................................................................14Frame Approach ................................................................................................................................................................15Cookie Approach ...............................................................................................................................................................16Separate Window Approach .............................................................................................................................................18View Document Example ..................................................................................................................................................18Checkout Document Example ..........................................................................................................................................20Checkin Document Example ............................................................................................................................................21Import Document Example ...............................................................................................................................................22Conclusion .........................................................................................................................................................................23

IntroductionUCF allows the content to be transferred directly between the client browser and the content server.To accomplish this, connection needs to be established between these two points. The UCF clientcode will need to execute on the user browser machine. It will require solid access to the user’smachine (i.e. to read and write the files, modify registry settings etc). In order to do this, the clientcode needs to execute either from within an applet or an Active X control. At the time of writing thisarticle, the ActiveX control for the UCF is still in the “early access” (seehttps://community.emc.com/docs/DOC-3501 for more details); therefore, in this article, we are going to focuson the applet. To make things interesting, however, we will integrate it with an ASP .NET application.While the code examples are in C# ASP .NET, the discussions regarding the use of applet shouldapply to people integrating UCF and DFS using other Java-based frameworks.Application OverviewThe example application will retrieve a list of documents and display them in a simple data grid. Theuser will be able to select a row in the data grid and view, check-out or check-in the selecteddocument. In addition, user will be able to upload a new file from his local hard drive. We areinterested in content only, so no metadata discussion.The following diagram shows our simple user interface:UCF APPLETEDIT CHECKOUT CHECKINGRIDVIEW CONTROLFILE INPUT CONTROLHIDDEN FIELDS CONTROLSExcept the UCF applet, all other controls are standard ASP .NET controls. Grid view control will beused to display a list of documents and process row selection. View, Checkout and Checkin buttonswill be used to execute the corresponding action on the document. File input control will be used to letthe user import a file. Hidden field controls will be used to store some values required to properlyinitialize the content transfer in the back-end code.Our client browser will be IE 6 with Sun Java Version 6 Update 14.

Now that our applet can successfully initialize, it is time to enhance the .NET application. Let us addthe necessary controls and integrate with DFS. We will be using the productivity layer.ASP .NET ApplicationDocument Listing ComponentFirst we will add code to display a list of documents in the Gridview control. The updated .aspx pagewill look like this:UCF and DFS Integration//called from the applet to set the valuesfunction initUcf(ucfId,jsessionId){alert('in ucf init, ucId is: ' + ucfId + ', jsessionid is: ' + jsessionId);}The code behind page will bind the Gridview to the list of DocumentInfo objects:

public partial class _Default : System.Web.UI.Page{public string SelectedObjectId{get { return ViewState["selectedObjectId"] != null ?(string)ViewState["selectedObjectId"] : null; }set { ViewState["selectedObjectId"] = value; }}protected void Page_Load(object sender, EventArgs e){if (!IsPostBack){DocumentHelper helper = new DocumentHelper();List docs = helper.GetDocuments();DocumentsGridView.DataSource = docs;DocumentsGridView.DataBind();}}}protected void DocumentsGridView_SelectedIndexChanged(object sender, EventArgs e){String objectId = DocumentsGridView.SelectedRow.Cells[0].Text;SelectedObjectId = objectId;}The SelectedIndexChanged method keeps track of the currently selected row and stores the object idin the ViewState cache. We will need this object id later during view / checkout functionality.DocumentInfo is a simple data model class:public class DocumentInfo{public string ObjectId { get; set;}public string DocumentName { get; set; }public string LockOwner { get; set; }}public DocumentInfo(){}Finally, the DocumentHelper is a utility class that integrates with the DFS query service:public List GetDocuments(){List documents = new List();IServiceContext context = ConfigUtil.GetDfsServiceContext();IQueryService querySvc =ServiceFactory.Instance.GetRemoteService(context, "core",ConfigUtil.DfsServerUri);PassthroughQuery query = new PassthroughQuery();

query.QueryString = "select r_object_id, object_name, r_lock_owner from dm_documentwhere object_name like '%Template%'";query.AddRepository(ConfigUtil.DefaultRepository);QueryExecution queryEx = new QueryExecution();queryEx.CacheStrategyType = CacheStrategyType.DEFAULT_CACHE_STRATEGY;OperationOptions operationOptions = null;QueryResult queryResult = querySvc.Execute(query, queryEx,operationOptions);DataPackage resultDp = queryResult.DataPackage;List dataObjects = resultDp.DataObjects;foreach (DataObject dObj in dataObjects){PropertySet docProperties = dObj.Properties;String objectId = dObj.Identity.GetValueAsString();String name = docProperties.Get("object_name").GetValueAsString();String lockedBy = null;Property lockOwner = docProperties.Get("r_lock_owner");if (lockOwner != null){lockedBy = lockOwner.GetValueAsString();}}DocumentInfo a1 = new DocumentInfo();a1.ObjectId = objectId;a1.DocumentName = name;a1.LockOwner = lockedBy;documents.Add(a1);}return documents;The ConfigUtil is a class with some utility methods / properties:public class ConfigUtil{public ConfigUtil(){}public static string DfsServerUri{get{string dfsServerUri = System.Configuration.ConfigurationManager.AppSettings["dfsServerUri"];return dfsServerUri;}}public static string DefaultRepository{get{string repo = System.Configuration.ConfigurationManager.AppSettings["defaultRepository"];return repo;}}public static string TestUser{

get{string user = System.Configuration.ConfigurationManager.AppSettings["testUser"];return user;}}public static string TestUserPassword{get{string password = System.Configuration.ConfigurationManager.AppSettings["testUserPassword"];return password;}}public static IServiceContext GetDfsServiceContext(){IServiceContext context = ContextFactory.Instance.NewContext();context.AddIdentity(new RepositoryIdentity(DefaultRepository, TestUser, TestUserPassword, ""));return context;}}The application’s web.config file contains the following custom entries:TIP: There are additional required configuration settings to configure DFS services. Please take alook at the full web.config provided as part of the Visual Studio Solution sample code and/or consultthe DFS Development Guide.TIP: The query will try to read contents of the /Templates cabinet. Make sure the test user you areusing has proper access permissions on that cabinet.The final display should look something like this:

Page PostBack and Browser Refresh ProblemThis is where things start to get interesting. Try to select one or two documents and monitor the JavaConsole. You will get an error like this:Exception in thread "Thread-1" com.documentum.ucf.common.transport.TransportError:com.documentum.ucf.common.transport.TransportStreamException: Unrecoverable stream error: HTTP session is notproperly initializedat com.documentum.ucf.client.transport.impl.ClientSession.run(ClientSession.java:420)Caused by: com.documentum.ucf.common.transport.TransportStreamException: Unrecoverable stream error: HTTPsession is not properly initializedat com.documentum.ucf.client.transport.impl.ClientReceiver.getRequests(ClientReceiver.java:53)at com.documentum.ucf.client.transport.impl.ClientSession.handshake(ClientSession.java:621)at com.documentum.ucf.client.transport.impl.ClientSession.handshake(ClientSession.java:600)at com.documentum.ucf.client.transport.impl.ClientSession.run(ClientSession.java:214)-1; Handshake failed…What happened? Clicking “Select” will cause the ASP .NET to post the page back to the server. Afterserver processing is complete, the page will be rendered again. Second time it renders, the applet willtry to reinitialize again. The init() method will be called and the applet will try to start another

UcfConnection. However, because this is the same HttpSession initialized previously, the code willfail.You can observer the same behavior just by clicking F5 (Refreshing the browser page).After the above exception is thrown, the process is broken (in addition, the code itself is veryinefficient - we do not want to start new UcfConnections on every postback). Depending on yourrequirements, there are few things you can do here.Frame ApproachOne way to fix this is to move the applet to a separate outer frame and include the .NET page insidea separate frame. This way, the applet will stay loaded and .NET postbacks will resubmit only theinner frame. The UcfConnection will be established only once and the process will be very efficient.The outer frame will look like this:DFS and UCF Integration//called from the applet to set the valuesfunction initUcf(ucfId,jsessionId){alert('in ucf init, ucId is: ' + ucfId + ', jsessionid is: ' + jsessionId);}The Deafult.aspx page stays the same as before just without the applet.TIP: Frame approach with a combination of cookies (more on this later) is the approach we arecurrently using. One problem we encountered was that our application had to be invoked withcertain URL parameters passed to it. This meant that the outer frame page had to propagate thesedown to the Default.aspx page. You can accomplish this using the asp literal control.

For example, instead of iframe tag in the outer .aspx page, you would have something like this:……Then in the code behind class do something like this:public partial class Outter : System.Web.UI.Page{protected void Page_Load(object sender, EventArgs e){string url = Request.Url.ToString();int paramStart = url.IndexOf("?");string newPrams = url.Substring(paramStart);LiteralFrame.Text = "";}}While the frame approach fixes the postback problem, the issue of the browser refresh still remains.The browser refresh will cause both frames to reload and the UcfConnection would fail to initialize.To make things worse, if the user navigates away to a different page (one without the applet) andthen revisits the applet page, same exception will happen.Using cookies and “rebinding” UcfConnection can help us solve this issue.Cookie ApproachIf you look at the constructors of the UcfConnection class, notice there are two – one takes just theDFS server URL as a parameter, while the other one takes in jsessionId and deploymentId as well.For example, if we know the jsessionId, we can open a new UcfConnection as follows:UcfConnection conn = new UcfConnection(new URL("http://soulshaker:7777/"),jsessionId, deploymentId);If the connection is established this way, the exception will not be thrown. So, we will modify thebehavior of our applet – initially it will establish a regular UcfConnection using just the URL in theconstructor. We will then obtain the jsessionId and store it as a cookie. Any possible subsequent callsto initialize the applet will first check if the cookie exist, and if so, rebind the UcfConnection to thesame HttpSession (identified by the jsessionId). Here is the modified applet init method code:public void init() {System.out.println("Cookie applet init()...");jsessionId = getCookie();System.out.println("read cookie jsession id as: " + jsessionId);if (jsessionId == null) {System.out.println("NO JSESSIONID COOKIE FOUND, starting NEW CONNECTION");

try {conn = new UcfConnection(new URL("http://soulshaker:7777/"));jsessionId = conn.getJsessionId();ucfId = conn.getUid();deploymentId = conn.getTargetDeploymentId();System.out.println("jsessionId=" + jsessionId + ", uid="+ ucfId);addCookie(jsessionId);System.out.println("added cookie");} catch (Exception e) {e.printStackTrace();}} else {System.out.println("FOUND jsession ID in cookie as: " + jsessionId);System.out.println("trying to reuse the connection with the old jsession id");try {conn = new UcfConnection(new URL("http://soulshaker:7777/"),jsessionId, deploymentId);}} catch (MalformedURLException e) {e.printStackTrace();} catch (UcfException e) {e.printStackTrace();}}// finally, pass the values to the asp .net pageJSObject win = JSObject.getWindow(this);win.call("initUcf", new Object[] { ucfId, jsessionId });The getCookie() and addCookie() are simple helper methods that use JavaPlugin to add/read cookiesfrom within the applet. Here is the example code:public void addCookie(String cookieValue) {JSObject myBrowser = JSObject.getWindow(this);JSObject myDocument = (JSObject) myBrowser.getMember("document");myDocument.setMember("cookie", cookieValue);}public String getCookie() {try {JSObject myBrowser = (JSObject) JSObject.getWindow(this);JSObject myDocument = (JSObject) myBrowser.getMember("document");String myCookie = (String) myDocument.getMember("cookie");if (myCookie != null && myCookie.length() > 0)return myCookie;} catch (Exception e) {e.printStackTrace();}return null;}IMPORTANT: It is important to realize that recreating and rebinding the UcfConnection this way stillspawns another javaw.exe process on the client machine. If you keep refreshing the page whilemonitoring the running processes on the client machine, you will notice this. The connectionseventually do time out and the processes terminate. In our case, this behavior was acceptable as

the browser refresh case (or the case where the user navigates away then comes back to theapplet page) are extremely rare. Your requirements might be different, so be careful.Finally, as will be discussed later, we will be setting the AutoCloseConnection parameter of theActivityInfo object to false. This allows us to reuse the UcfConnection multiple times. Ideally, weshould be manually closing the connection. Applets have a stop() method called right before JVMshuts down – this appeared like a perfect place for us to close the connection. Unfortunately, thefollowing throws an IOException:public void stop() {System.out.println("closing connection");conn.closeConnection();super.stop();}This article will be updated if a proper way to manually close the connection is discovered.Please email the author if you have ideas regarding this issue.Separate Window ApproachWhile this approach is not discussed in this article, if your requirements allow it, you could alwaysopen an additional window that would hold the applet. You could add a statment like “Please do notclose or refresh this window while your session is in progress”.View Document ExampleAt this point, we should have a stable applet that retrieves the required jsessionId and ucfIdparameters and passes it to a JavaScript function initUcf, which will store these values using hiddenfields.First, add the hidden field controls to your Default.aspx page (page containing the data grid):Next, update the initUcf function in the Outter.aspx. Remember, the applet is contained on the outerframe, so the JavaScript will have to access the fields from the Doclist.aspx inner frame ://called from the applet to set the valuesfunction initUcf(ucfId,jsessionId){alert('in ucf init, ucId is: ' + ucfId + ', jsessionid is: ' + jsessionId);//get the frame and the top form in the framevar topFrame = window.frames['mainFrame'];var topFrameForm = topFrame.document.getElementById("form1");//set the values of hidden fields on the included pagetopFrameForm.UcfIdText.value = ucfId;topFrameForm.JsessionIdText.value = jsessionId;}

The utility methods of the ConfigUtil used in the above code are implemented as follows:public static ContentTransferProfile GetUcfContentTransferProfile(string jsessionId, string ucfId){ActivityInfo activityInfo = GetActivityInfo(jsessionId, ucfId);ContentTransferProfile ctProfile = new ContentTransferProfile();ctProfile.TransferMode = ContentTransferMode.UCF;ctProfile.AllowCachedContentTransfer = true;ctProfile.transferModeSpecified = true;ctProfile.ActivityInfo = activityInfo;return ctProfile;}Notice that we set the AutoCloseConnection parameter of the ActivityInfo object to false in order to beable to reuse the UcfConnections in the applet.public static ActivityInfo GetActivityInfo(string jsessionId, string ucfId){ActivityInfo activityInfo = new ActivityInfo();activityInfo.ActivityId = ucfId;activityInfo.SessionId = jsessionId;activityInfo.AutoCloseConnection = false;return activityInfo;}public static ObjectIdentitySet GetObjectIdentitySet(String objectId){return new ObjectIdentitySet(GetObjectIdentity(objectId));}public static ObjectIdentity GetObjectIdentity(String objectId){return new ObjectIdentity(new ObjectId(objectId), DefaultRepository);}Checkout Document ExampleCheckout is implemented in a similar way. Here is the implementation in the DocumentHelper:public void CheckoutDocument(string objectId, string jsessionId, string ucfId){//sanity check for the argumentsif (string.IsNullOrEmpty(objectId))throw new Exception("viewdocument, objectId is null");if (string.IsNullOrEmpty(jsessionId))throw new Exception("viewdocument, jsessionId is null");if (string.IsNullOrEmpty(ucfId))throw new Exception("viewdocument, ucfId is null");IServiceContext context = ConfigUtil.GetDfsServiceContext();IVersionControlService versionService =ServiceFactory.Instance.GetRemoteService(context, "core", ConfigUtil.DfsServerUri);ContentTransferProfile ctProfile = ConfigUtil.GetUcfContentTransferProfile(jsessionId, ucfId);//set the content transfer profile on the operationOperationOptions operationOptions = new OperationOptions();operationOptions.ContentTransferProfile = ctProfile;//set the content transfer profile on the contextcontext.SetProfile(ctProfile);

set the dfs content profile to editContentProfile contentProfile = new ContentProfile();contentProfile.FormatFilter = FormatFilter.ANY;contentProfile.PostTransferAction = "dfs:edit";operationOptions.ContentProfile = contentProfile;}versionService.Checkout(ConfigUtil.GetObjectIdentitySet(objectId), operationOptions);Checkin Document ExampleCheckin is also very similar. Notice how we do NOT specify the location of the actual content itself,only the object id. The DFS and UCF integration is smart enough to properly resolve this based onthe object id (i.e. it will check the registry and obtain the exact location where the document waspreviously checked out). This will work properly even in the cases where the document was renamedwith a suffix (i.e. testdoc_01.doc) – this happens if a resource with a same name is already checkedout.public void CheckingDocument(string objectId, string jsessionId, string ucfId){//sanity check for the argumentsif (string.IsNullOrEmpty(objectId))throw new Exception("viewdocument, objectId is null");if (string.IsNullOrEmpty(jsessionId))throw new Exception("viewdocument, jsessionId is null");if (string.IsNullOrEmpty(ucfId))throw new Exception("viewdocument, ucfId is null");IServiceContext context = ConfigUtil.GetDfsServiceContext();IVersionControlService versionService =ServiceFactory.Instance.GetRemoteService(context, "core", ConfigUtil.DfsServerUri);//set the UCF content transfer profile on contextContentTransferProfile ctProfile = ConfigUtil.GetUcfContentTransferProfile(jsessionId, ucfId);context.SetProfile(ctProfile);//set the UCF content transfer profile on the opsOperationOptions operationOptions = new OperationOptions();operationOptions.ContentTransferProfile = ctProfile;CheckinProfile checkinProfile = new CheckinProfile();checkinProfile.DeleteLocalFileHint = true;checkinProfile.MakeCurrent = true;operationOptions.CheckinProfile = checkinProfile;//set the dfs content profile to generic (i.e. no post view / post edit action)ContentProfile contentProfile = new ContentProfile();contentProfile.FormatFilter = FormatFilter.ANY;operationOptions.ContentProfile = contentProfile;DataObject dataObject = new DataObject(ConfigUtil.GetObjectIdentity(objectId));DataPackage dataPackage = new DataPackage(dataObject);}versionService.Checkin(dataPackage, VersionStrategy.SAME_VERSION, false, null, operationOptions);

Import Document ExampleTo allow document import, first add the file input control and a new upload file button controls to yourASP .NET page:Implemented the method handler for the upload button:protected void UploadDocument_Click(object sender, EventArgs e){//this assumes the user selected a row in the data grid first//get the values of the hidden fieldsstring jsessionId = JsessionIdText.Value;string ucfId = UcfIdText.Value;string filePath = FileToUpload.PostedFile.FileName;}DocumentHelper docHelper = new DocumentHelper();docHelper.UploadDocument(filePath, jsessionId, ucfId);And finally, here is the actual UploadDocument method on the handler. Notice that the code is a bitsimplified – it will always create the document and name it “DFS and UCF Imported Document” as aPDF document.public void UploadDocument(string filePath, string jsessionId, string ucfId){//sanity check for the argumentsif (string.IsNullOrEmpty(filePath))throw new Exception("viewdocument, objectId is null");if (string.IsNullOrEmpty(jsessionId))throw new Exception("viewdocument, jsessionId is null");if (string.IsNullOrEmpty(ucfId))throw new Exception("viewdocument, ucfId is null");IServiceContext context = ConfigUtil.GetDfsServiceContext();ContentTransferProfile ctProfile = ConfigUtil.GetUcfContentTransferProfile(jsessionId, ucfId);context.SetProfile(ctProfile);ServiceFactory serviceFactory = ServiceFactory.Instance;IObjectService objectService = serviceFactory.GetRemoteService(context, "core",ConfigUtil.DfsServerUri);// DEFINE new documentObjectIdentity documentId = new ObjectIdentity(ConfigUtil.DefaultRepository);DataObject documentObject = new DataObject(documentId, "dm_document");documentObject.Properties.Set("object_name", "DFS and UCF Imported Document");// ADD the folder ReferenceRelationship - we are saving in the Temp folderObjectPath objectPath = new ObjectPath("/Temp");ObjectIdentity folderIdentity = new ObjectIdentity(objectPath, ConfigUtil.DefaultRepository);ReferenceRelationship folderRelationship = new ReferenceRelationship();folderRelationship.Name = Relationship.RELATIONSHIP_FOLDER;folderRelationship.Target = folderIdentity;folderRelationship.TargetRole = Relationship.ROLE_PARENT;

documentObject.Relationships.Add(folderRelationship);//only support pdf types. you will need to add some sort of format recognizer//configuration settings to determine the documentum content type depending//on the submited file (i.e. if file extension = doc, dctmcontent type = msw8 etc)String dctmContentType = "pdf";// ADD UCF content to documentUcfContent ucfContent = new UcfContent(filePath, dctmContentType);documentObject.Contents.Add(ucfContent);objectService.Create(new DataPackage(documentObject), new OperationOptions());}ConclusionHopefully this article shed some light on the required orchestration of events that need to happen forthe DFS and UCF integration.Email the author at mirza.fazlic@gmail.com with any comments and suggestions.