| Oracle® Workspaces Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25480-01 |
|
|
View PDF |
| Oracle® Workspaces Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25480-01 |
|
|
View PDF |
This chapter describes the following requirements and tasks involved in building applications with Oracle Workspaces Java API:
This section describes settings you must configure before executing applications that use Oracle Workspaces Java API.
Run Java applications that use the Oracle Workspaces Java API from a machine on which Oracle Collaboration Suite Applications tier is installed.
Set your CLASSPATH environment variable to include the following files, where the environment variable ORACLE_HOME is set to the directory of your Oracle Collaboration Suite instance:
$ORACLE_HOME/discussions/lib/discussions.jar $ORACLE_HOME/j2ee/home/jazncore.jar $ORACLE_HOME/j2ee/home/lib/connector.jar $ORACLE_HOME/j2ee/home/lib/ejb.jar $ORACLE_HOME/j2ee/home/lib/http_client.jar $ORACLE_HOME/j2ee/home/lib/jaas.jar $ORACLE_HOME/j2ee/home/lib/jms.jar $ORACLE_HOME/j2ee/home/lib/jndi.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/ applications/workspaces/workspaces/WEB-INF/lib/rtcSDK.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/ applications/workspaces/workspaces/WEB-INF/lib/files_searchlet.jar $ORACLE_HOME/jdbc/lib/classes12.jar $ORACLE_HOME/jlib/collabsuiteuser.jar $ORACLE_HOME/jlib/esadmin.jar$ORACLE_HOME/jlib/escommon.jar $ORACLE_HOME/jlib/esldap.jar $ORACLE_HOME/jlib/esmail_sdk.jar $ORACLE_HOME/jlib/javax-ssl-1_1.jar $ORACLE_HOME/jlib/jssl-1_1.jar $ORACLE_HOME/jlib/ldap.jar $ORACLE_HOME/jlib/ldapjclnt10.jar $ORACLE_HOME/jlib/ocsaddressbook.jar $ORACLE_HOME/jlib/ocscommon.jar $ORACLE_HOME/jlib/ojmisc.jar $ORACLE_HOME/jlib/providerutil.jar $ORACLE_HOME/jlib/repository.jar $ORACLE_HOME/lib/activation.jar $ORACLE_HOME/lib/dms.jar $ORACLE_HOME/lib/mail.jar $ORACLE_HOME/lib/servlet.jar $ORACLE_HOME/lib/xmlparserv2.jar $ORACLE_HOME/ocal/jlib/ocal_clnt.jar $ORACLE_HOME/soap/lib/soap.jar $ORACLE_HOME/workspaces/lib/workspaces_sdk.jar $ORACLE_HOME/workspaces/lib/workspaces_share.jar $ORACLE_HOME/ultrasearch/lib/searchlet.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ rtcSDK.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ content-ws-client.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ axis.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ jaxrpc.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ commons-logging.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ commons-discovery.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ saaj-api.jar $ORACLE_HOME/j2ee/OC4J_OCSClient/applications/workspaces/workspaces/WEB-INF/lib/ wsdl4j.jar $ORACLE_HOME/jlib/orai18n-js.jar
You must provide a configuration file that instructs how your Oracle Workspaces applications connect to Oracle Collaboration Suite Service Registry (in Oracle Internet Directory), which, in turn, provides your application with information about the Oracle Workspaces instance to which it connects. This file should be deployed on your server and made readable by your applications. (See "Java System Properties" to see how this file is used by applications.)
Create a file with the following contents. (Ensure that you change the Oracle Internet Directory settings to reflect your Oracle Collaboration Suite deployment:
# ----------------------------------------- # Logging Settings (OC4J is for debugging) # ----------------------------------------- # For more info (very verbose), set this log level to debug oracle.workspaces.log.level = fatal # ----------------------------------------- # Oracle Internet Directory Settings # ----------------------------------------- oracle.ocs.ldappool.host = my-company.com oracle.ocs.ldappool.port = 3060 oracle.ocs.ldappool.user_dn = cn=orcladmin oracle.ocs.ldappool.user_password = welcome1 # If not in an OC4J container, then skip events cw.test.use_jms = n
This section describes Java system properties you must set and how to log in and initialize Oracle Workspaces.
Before creating a connection to an Oracle Workspaces instance, your application needs to know which instance to connect to. Oracle Workspaces stores its connection information in the Collaboration Suite Service Registry, which is stored in Oracle Internet Directory. Therefore, you need to provide a configuration file (which has been described previously). Initializing and logging into the Oracle Workspaces system involves the following steps:
Set the following system properties when you execute your Java application:
Table 3-1 Java System Properties
| System Property | Description |
|---|---|
|
cw.configFile |
The name of your configuration file |
|
oracle.ons.oraclehome |
$ORACLE_HOME |
|
java.library.path |
$ORACLE_HOME/lib:$ORACLE_HOME/ocal/lib |
|
oracle.home |
$ORACLE_HOME |
|
oracle.ons.instancename |
The name of the OracleAS Infrastructure instance. You can find the instance name in $ORACLE_HOME/config/ias.properties as follows:
|
You may use one of the following options to set these properties:
Use the -D option to set these properties if you are executing your Java application from the command line.
Call the System.setProperty method to set these properties within your Java code
The following code extract sets required system properties:
public void init(ServletConfig config) throws ServletException
{
super.init(config);
String O_H="/home/user1/m12d/apps";
System.setProperty(
"cw.configFile",
"/home/user1/samples/workspaces/cwConfigFile");
System.setProperty("oracle.ons.oraclehome", O_H);
System.setProperty("oracle.home", O_H);
System.setProperty(
"oracle.ons.instancename",
"ocsapps.collabtng15.us.oracle.com");
}
The following example initializes Oracle Workspaces, grants a specified user workspace creator role, and logs that user into Oracle Workspaces. Note that you will probably not grant workspace roles in your applications; this example is here for informational purposes. However, Oracle Workspaces initialization and logging in as a user will be performed in each of your applications.
This example performs the following steps:
Calls the CwService.init() method to initialize Oracle Workspaces. Ensure that you have configured the appropriate Oracle Internet Directory settings in your configuration file.
Opens a session with a user who has application administration rights.
With this application administrator session, grants workspace creator roles to a specified user.
Logs in to the system by opening a new session with the specified user.
import oracle.workspaces.CwService;
import oracle.workspaces.authorization.CwApplicationRole;
import oracle.workspaces.authorization.CwUser;
import oracle.workspaces.session.CwSession;
public class Initialization {
public static CwService initializeService()
throws Exception
{
try {
// The method CwService.init() must be called before
// performing any Oracle Workspaces operations
CwService.init();
CwService currentService = CwService.getInstance();
return currentService;
} catch (Throwable t) {
t.printStackTrace();
System.exit(1);
}
}
public static CwUser createAppAdmin(
CwService currentService, String appAdminName)
throws Exception
{
// Obtain a user instance of the user from Oracle Internet Directory
CwUser appAdminUser = currentService.getUserByName(appAdminName);
// Open a session as a user with application administration
// rights. orcladmin has this by default.
CwSession orclAdminSession =
currentService.openSession(currentService.getUserByName("orcladmin"));
// Grant workspace creator role to the user
orclAdminSession.grant(
CwApplicationRole.CW_APPLICATION_ROLE_WORKSPACE_CREATORS,
appAdminUser);
return appAdminUser;
}
public static CwSession loginUser(CwService currentService, CwUser currentUser)
throws Exception
{
// Login to the Oracle Workspaces system by opening a session with the user
return currentService.openSession(currentUser);
}
public static void main(String[] args)
throws Exception
{
CwService myService = initializeService();
CwUser myAppAdminUser = createAppAdmin(
myService,
"application.administrator");
CwSession myAdminSession = loginUser(myService, myAppAdminUser);
}
}
The CwService class exposes the following APIs:
System management: Use the methods init and destroy to initialize the Oracle Workspaces system. Call these methods in the client application only once during the lifetime of the application.
Session management: Use the openSession and closeSession methods to open new or existing sessions and close existing sessions. Call the getIdentityById method to get a identity (user or group) instance based on its ID. The ID of an identity is the orclGuid attribute of the entry in Oracle Internet Directory. The methods getUserByDn() and getUserByName() respectively return an instance of CwUser given the DN or name of the user.
System management methods are static methods, while session management methods must be invoked on the instance returned by the getInstance() method.
The CwSession class exposes the following APIs:
Workspace management: These methods create workspaces, delete workspaces, retrieve a workspace's instance given its ID or path, and lists all accessible workspaces.
Template management: These methods create a template from a workspace, as well as store, delete, and list templates. Once a template is created, it can be used to create a new workspace using the createWorkspace() method.
Session management: These methods return session information such as last login or logout time.
Privilege management: These methods grant, revoke, and list application-level roles.
Recovery management: These methods find information about failed operations that require recovery and recover workspaces and the CW system from these failed operations.
See Appendix A, "Workspace and Application Properties" for a list of application properties that can be retrieved and specified. These properties let an application administrator specify the default template to be used for new templates and the workspace creation mode.
This section describes how to create workspaces, search for existing workspaces, and set workspace properties.
The CwWorkspace and CwWorkspaceDefinition classes are used to manage workspaces in the system. The CwSession class is used to create workspaces.
Workspaces are typically created from an existing template.
The CwWorkspace class exposes the following API:
Resource management: These methods create, delete, and list resources in the workspace.
Workspace property management: These methods retrieves and updates the workspace's properties. Workspace properties include the workspace's name, description, and configuration options. These methods do not provide information about the properties of its sub-workspaces.
Membership management: These methods add, remove, and list members and subgroups in the workspace.
Member role management: These methods lists and reassigns roles to members of the workspace.
An instance of this class contains all the information needed to create a workspace or subworkspace.
The following method returns a new workspace based on the default system template:
public static CwWorkspace
createWorkspaceWithAllResources(
CwSession session,
String workspaceName,
String workspaceDisplayname,
String workspaceDescription)
throws Exception
{
// Create a workspace definition object
CwWorkspaceDefinition wspcDef = new CwWorkspaceDefinition();
// Set the workspace name, display name, and description
// in the workspace definition object.
//
// Both name and display name must be unique.
wspcDef.setName(workspaceName);
wspcDef.setDisplayName(workspaceDisplayname);
wspcDef.setDescription(workspaceDescription);
// Use the default system template (set to "Basic Workspace Template"
// upon installation), which includes
// calendar (meetings & tasks),
// discussion board and inbox
String defaultTemplateName =
session.getCwApplicationPropertyValue(
CwPropertyConstants.DEFAULT_WORKSPACE_TEMPLATE_NAME);
// Create a workspace template object
CwWorkspaceTemplate template =
session.getWorkspaceTemplate(defaultTemplateName);
// Set the template in the workspace definition object
wspcDef.setTemplate(template);
// Create the workspace with the workspace definition object
CwWorkspace newWspc = session.createWorkspace(wspcDef);
return (newWspc);
}
The following code excerpt creates a new workspace:
// mySession is an open session CwWorkspaceDefinition wspcDef = new CwWorkspaceDefinition(); // Both the name and display name must be unique. wspcDef.setName("Workspace name"); wspcDef.setDisplayName("Workspace display name"); wspcDef.setDescription("Worspace definition"); CwWorkspace newWorkspace = mySession.createWorkspace(wspcDef);
For a list of workspace properties, see Appendix A, "Workspace and Application Properties".
This section describes how to do the following:
Manage the following resources, resource items, and other content that may be found in a workspace:
To create a resource or a resource item, instantiate the corresponding definition class. A definition class contains the set of properties that may be used to instantiate the resource or item. Required properties are included in the constructor of the definition class. Optional properties and additional information may be set by using methods on the definition class.
An instance of the definition class is only used at creation time. Once a resource or item is instantiated, the corresponding definition instance is never used again.
The following is an example of creating a calendar resource:
CwResourceDefinition calDefn =
new CwResourceDefinition(
"CalResource",
"My calendar resource",
CwEntityType.CALENDAR_RESOURCE);
CwCalendarResource calResource =
(CwCalendarResource)workspace.createResource(calDefn);
The following is an example of creating an event:
CwEventDefinition meetingDefn = new CwEventDefinition(
CwCalendarConstants.EVENT_TYPE_APPOINTMENT,
"my meeting summary",
startTime,
endTime);
CwEvent meeting = calResource.createEvent(meetingDefn);
Resources are also created when a workspace is created with a template. Define the resources you would like to create in the workspace template. To get a resource object, call one of the CwWorkspace.getResource methods such as getResourceByType.
To view or make any changes to the properties, retrieve an instance of the corresponding properties class.
The following is an example of retrieving an instance of a calendar resource properties class:
CwCalendarResourceProperties calProps = (CwCalendarResourceProperties)calResource.getProperties();
The following is an example of retrieving an instance of an event Properties class:
CwEventProperties eventProps = (CwEventProperties)meeting.getProperties();
The methods on the Properties classes are very similar to those on the Definition classes. In addition, additional system generated properties, such as getCreatedTime and getUID, are available from the Properties class.
Properties are not immediately saved when they are set on a Properties instance. To save the changes on a Properties instance, call the storeProperties method. This method looks at all the changes made to the Properties instance since the last call, and saves all those changes to the repository. This enhances performance because the database is accessed only once during a single call to storeProperties, instead of every time a property is changed.
Call the CwWorkspace.createMemberable method to create a member (of class CwMemberable) from a CwUser object.
The following code excerpt adds two members (one who has a reader role and other who has a writer role) to an existing workspace:
// newWorkspace is a workspace that has already been created. // // currentSession is a session opened by a user with the // administrator role in the workspace newWorkspace. CwUser userReader1, userWriter1; private static String userReader1Name = "Reader"; private static String userWriter1Name = "Writer"; userReader1 = currentSession.getUserByName(userReader1Name); userWriter1 = currentSession.getUserByName(userWriter1Name); CwMemberable[] membersToBeAdded = new CwMemberable[2]; membersToBeAdded[0] = newWorkspace.createMemberable( userReader1, CwMemberRoleType.CW_MEMBER_ROLE_READER); membersToBeAdded[1] = newWorkspace.createMemberable( userWriter1, CwMemberRoleType.CW_MEMBER_ROLE_WRITER); // Now, add the members to the workspace CwAddWorkspaceMembersResponse response = newWorkspace.addMembers(membersToBeAdded); CwMember[] addedMembers = response.getSuccessfulMembers(); CwMemberable[] failedMembers = response.getFailedMemberables(); Throwable[] failedExceptions = response.getFailedExceptions();
The CwCalendarResource class represents a calendar resource, and the CwEvent class represents an event resource item or a meeting.
The following code excerpt creates one meeting with a duration of one hour that will occur one hour after the current date and time:
// The workspace myWorkspace has already been created. It // has a calendar resource created in it. long m_referenceTime = Calendar.getInstance().getTimeInMillis(); // Startime: Create a meeting that starts one hour // after the current time java.util.Calendar start = new GregorianCalendar(); start.setTimeInMillis(m_referenceTime); start.set(Calendar.SECOND, 0); // ignore the seconds start.set(Calendar.MILLISECOND, 0); // ignore the milliseconds start.add(Calendar.DAY_OF_MONTH, 0); start.add(Calendar.HOUR_OF_DAY, 1); // Endtime: The meeting will be one hour long java.util.Calendar end = new GregorianCalendar(); end.setTimeInMillis(m_referenceTime); end.add(Calendar.DAY_OF_MONTH, 0); end.add(Calendar.HOUR_OF_DAY, 2); end.set(Calendar.SECOND, 0); // ignore the seconds end.set(Calendar.MILLISECOND, 0); // ignore the milliseconds // Create an event definition object CwEventDefinition evtDef = new CwEventDefinition( CwCalendarConstants.EVENT_TYPE_APPOINTMENT, "New Meeting Title", start.getTime(), end.getTime()); // Set attending type: ALL GROUP MEETING (default) // Note: Since this is an all group meeting, it will // automatically invite all workspace members. // // To create a meeting with a subset of workspace members as // attendees, set the attending type to // CwCalendarConstants.ATTENDING_TYPE_SUBGROUP and use the // CwEventDefinition.setAttendees method to set the list of attendees evtDef.setAttendingType(CwCalendarConstants.ATTENDING_TYPE_ALL); // Set event description evtDef.setDescription("Create an event through OCW API"); // Set event priority evtDef.setPriority(CwCalendarConstants.PRIORITY_NORMAL); // Create a reminder CwCalendarAlarm alm = new CwCalendarAlarm(); alm.setAction(CwCalendarAlarm.ACTION_EMAIL); alm.setEmail("testUser@oracle.com"); alm.setMinutes(10); evtDef.addAlarm(alm); // Create event // // First, get the calendar resource CwCalendarResource m_calResource = (CwCalendarResource) myWorkspace. getResourceByType(CwResourceType.CALENDAR_RESOURCE); CwEvent event = m_calResource.createEvent(evtDef); CwEventProperties resProps = (CwEventProperties)event.getProperties(); System.out.println("Done Creating Meeting:" + resProps.getSummary());
The CwDiscussionResource class represents a discussion resource; CwBoard, a discussion board; and CwMessage, a message.
The following code excerpt creates a discussion board in an existing workspace, and posts a message and a reply to that message on the new board:
// The workspace myWorkspace has already been created. It // has a discussion resource created in it. // Retrieve discussion resource CwDiscussionResource m_discResource = (CwDiscussionResource) myWorkspace.getResourceByType( CwResourceType.DISCUSSION_RESOURCE)); // Create a discussion board definition object CwBoardDefinition maxBoardDef = new CwBoardDefinition( "New Board", "A test board", "board.email@my.company.com"); maxBoardDef.setDescription("Description of new board"); maxBoardDef.setSubjectReplyPrefix("Re: "); maxBoardDef.setOriginalQuoted(true); maxBoardDef.setBeginQuotePrefix("> "); // Create a discussion board CwBoard maxBoard = m_discResource.createBoard(maxBoardDef); // Post a message on the new board CwMessageDefinition msgDef = null; msgDef = new CwMessageDefinition(); msgDef.setSubject("Subject of new message"); msgDef.setText("Text of new message"); // Create message CwMessage createdMessage = maxBoard.createMessage(msgDef); // Post a reply to the message // Create message definition for the reply. CwMessageDefinition msgDefReply = null; msgDefReply = new CwMessageDefinition(createdMessage); msgDefReply.setSubject("Subject of reply message"); msgDefReply.setText("Text of reply message"); // Create reply CwMessage replyMessage = maxBoard.createMessage(msgDefReply);
The email resource, represented by the CwEmailResource class, uses a discussion board resource item to manage its messages. This discussion board is the workspace's inbox.
Therefore, in order to manage an email resource's messages, first retrieve the resource's discussion board by calling the CwEmailResource.getBoard method. Manage the email resource's messages by calling methods on the discussion board object.
The following code excerpt creates an email resource in an existing worspace and retrieves its discussion board:
// myWorkspace is an existing workspace. // emailDomain is a string representing // the email domain name such as my-company.com. // Create an email resource in myWorkspace CwEmailResourceDefinition rsrcDef = new CwEmailResourceDefinition( "em_rsrc", "email resource description", "emailrsrc1" + emailDomain // emailrsrc1@my-company.com ); CwEmailResource emailResource = (CwEmailResource)(myWorkspace.createResource(rsrcDef)); // Get the discussion board underlying the email resource CwBoard rsrcBoard = emailResource.getBoard(); // Once the board object is obtained, all operations that can be performed // on a board can be performed on the email resource
Call CwFilesResource.getWorkspaceFolder to retrieve the root folder of the workspace. Add new folders and files to this folder.
The following code excerpt adds a file to an existing workspace.
// myWorkspace is a workspace that has a files // resource. // Get the files resource from the workspace CwFilesResource files = (CwFilesResource) myWorkspace.getResourceByType(CwResourceType.FILES_RESOURCE); // Create the new file CwFileDefinition docDef = new CwFileDefinition("My_New_Document.txt", "Contents of new file"); docDef.setDescription("Description of new file"); // Retrieve the workspace folder CwFolder myWorkspaceFolder = files.getWorkspaceFolder(); // Add the document to the workspace folder CwFile rfpDoc = myWorkspaceFolder.createFile(docDef);
The following code excerpt performs the following operations:
Retrieve the files resoruce from an existing workspace
Create a folder in the root folder
Retrieve and update the properties of a folder
List contents of a folder
Delete items in a folder
// myWorkspace is an exisitng workspace with // a files resource // Retrieve files resource CwFilesResource m_filesRsrc = (CwFilesResource) myWorkspace.getResourceByType(CwResourceType.FILES_RESOURCE); // Create a folder in the workspace CwFolder wspcFolder = m_filesRsrc.getWorkspaceFolder(); CwFolderDefinition subfolderDef = new CwFolderDefinition("TEST_SUBFOLDER_NAME"); subfolderDef.setDescription("TEST_SUBFOLDER_DESC"); CwFolder subfolder = wspcFolder.createFolder(subfolderDef); // Get the properties of a folder CwFolderProperties props = (CwFolderProperties) subfolder.getProperties(); System.out.println("name: " + props.getName()); System.out.println("description: " + props.getDescription()); // Update properties of a folder props.setName("props_test2"); props.setDescription("description2"); subfolder.storeProperties(); // List contents of a folder CwFilesResourceItem[] contents = wspcFolder.listContents(); // fldr1, fldr2, and file1 two folders and a file // that have been previously initialized and added to the root folder. // Delete items in a folder CwUid[] uids = new CwUid[] {fldr1.getUid(), fldr2.getUid(), file1.getUid()}; wspcFolder.deleteItems(uids);
The class CwAnnouncementList manages announcements. Announcements are of type CwAnnouncement. However, CwAnnouncementList is not a resource; it is managed directly by the CwWorkspace class.
The following code excerpt creates an announcement in an existing workspace with an expiration date of one week from today's date:
// workspaceUid is a UID of an exisitng workspace CwWorkspace myWorkspace = mySession.getWorkspaceByUid(workspaceUid); CwAnnouncementList anncList = myWorkspace.getAnnouncementList(); // Create an announcement // Create the expiration date of the announcement: // one week from today long m_referenceTime = java.util.Calendar.getInstance().getTimeInMillis(); java.util.Calendar myCalendar = new java.util.GregorianCalendar(); myCalendar.setTimeInMillis(m_referenceTime); myCalendar.add(java.util.Calendar.DAY_OF_YEAR, 7); java.util.Date oneWeekLater = myCalendar.getTime(); // Create an announcement definition object CwAnnouncementDefinition anncDef1 = new CwAnnouncementDefinition( "announcement test1", "Welcome user wspcUser1 to the workspace.", "text/plain", oneWeekLater); // Create the announcement on the announcement list // and retrieve the UID of the announcement CwUid anncUid1 = anncList.createAnnouncement(anncDef1).getUid();
The following code excerpt performs several operations on announcements:
// anncUid1, anncUid2, anncUid3, and anncUid4 // are UIDs of announcements. // anncList is an announcement list of a workspace. // List an announcement by its UID CwAnnouncement annc1Got = (CwAnnouncement)anncList.getItemByUid(anncUid1); // List unexpired announcements in the workspace CwAnnouncement anncs[] = anncList.listUnexpiredAnnouncements(); // Update an announcement String newDescription = "This Friday team lunch is rescheduled to Monday."; CwAnnouncement annc2Got = (CwAnnouncement)anncList.getItemByUid(anncUid2); annc2Got.getProperties().setDescription(newDescription); annc2Got.storeProperties(); // Delete an announcement anncList.deleteAnnouncement(anncUid2); // Delete multiple announcements anncList.deleteAnnouncements(new CwUid[]{anncUid3, anncUid4});
An attachment (which is called a link in the Oracle Workspace Web client) is a mechanism that associates resource items with each other. Because the CwResourceItem class implements the CwAttachmentEnabled interface, all resource items have the ability to link to other resource items.
Use the createAttachment method to link resource items. Once an attachment is created, a uni-directional link is formed with metadata retained to remember which resource item is the source and which is the destination. The CwAttachmentEnabled.listAttachments method finds all items that the current item points to. The CwAttachmentEnabled.listSourceAttachments method finds all items that point to the current item.
The CwAttachedEntity class represents an attachment. CwAttachmentDefinition represents a resource item to be attached. No resource class exists for attachments; they are directly managed by workspaces. Call CwWorkspaces.addAttachments to create an attachment in a workspace.
The following code excerpt performs the following operations:
Attach an item to another item
Attach multiple attachments
List all attachments
List attachments by type
Update descriptions of specified attachments
Remove specified attachments
// workspaceUid is a UID of an existing workspace CwWorkspace myWorkspace = mySession.getWorkspaceByUid(workspaceUid); // Attach a single item to a given item // childEntityUid1 is a UID of resource item in the current // workspace that will be attached to parentEntityUid, a UID // of another resource item in the workspace. CwAttachmentDefinition attchDef1 = new CwAttachmentDefinition( childEntityUid1, "Attachment description"); myWorkspace.addAttachments(parentEntityUid, attchDef1); // Add multiple attachments CwAttachmentDefinition attchDef2 = new CwAttachmentDefinition( new CwUid[] {childEntityUid2,childEntityUid3}, "Multiple attachments with the same description"); myWorkspace.addAttachments(parentEntityUid, attchDef2); // List all attachments CwAttachedEntity[] myAttachments = myWorkspace.listAttachments( parentEntityUid ); System.out.println( "listing attachment uids:" ); for (int i = 0; i < myAttachments.length; i++) { System.out.println( "\tattachment # " + i ); System.out.println( "\t\tattachment uid = " + myAttachments[i].getEntityUid().toString() ); System.out.println( "\t\tattachment description = " + myAttachments[i].getDescription() ); System.out.println( "\t\tattachment role = " + myAttachments[i].getEntityRole() ); } // Listing attachments by type Map myAttachmentsMap = myWorkspace.listAttachmentsByType( parentEntityUid ); Set myAttachmentsSet = myAttachmentsMap.entrySet(); Object[] myAttachmentsArray = myAttachmentsSet.toArray(); for (int i = 0; i < myAttachmentsArray.length; i++) { System.out.println( "\tattachment type = " + ((CwEntityType)(((Map.Entry)myAttachmentsArray[i]).getKey())).getName() ); CwAttachedEntity[] myAttachmentsSameType = ((CwAttachedEntity[])(((Map.Entry)myAttachmentsArray[i]).getValue())); for (int j = 0; j < myAttachmentsSameType.length; j++) { System.out.println( "\t\tattachment # " + j ); System.out.println( "\t\t\tattachment uid = " + myAttachmentsSameType[j].getEntityUid().toString() ); System.out.println( "\t\t\tattachment description = " + myAttachmentsSameType[j].getDescription() ); System.out.println( "\t\t\tattachment role = " + myAttachmentsSameType[j].getEntityRole() ); } } // Update attachment descriptions CwAttachedEntity[] attachments = myWorkspace.listAttachments( parentEntityUid ); // Update entities 1 and 2 attachments[0].setDescription( attachments[0].getDescription() + " - Updated"); attachments[1].setDescription( attachments[3].getDescription() + " - Updated"); myWorkspace.updateAttachments( parentEntityUid, attachments); // Remove attachments attachments = myWorkspace.listAttachments( parentEntityUid ); // Remove entities 1 and 2 CwAttachedEntity[] toBeRemovedEntities = new CwAttachedEntity[2]; toBeRemovedEntities[0] = attachments[0]; toBeRemovedEntities[1] = attachments[3]; myWorkspace.removeAttachments( parentEntityUid, toBeRemovedEntities);
The CwViewResource class represents a View resource, and the CwView class represents a view.
The following excerpt performs the following operations:
Create a new view in an existing workspace
Update properties of that new view
Retrieve a view by UID
List the views of a workspace
List the items in a view
Delete views
Delete a view resource
// myWorkspace is an exisitng workspace // Add the view resource to an existing workspace CwResourceDefinition resDef = new CwResourceDefinition( "Views", "View resource", CwResourceType.VIEW_RESOURCE ); CwViewResource viewRes = (CwViewResource)myWorkspace.createResource( resDef ); // Create a new view CwViewDefinition viewDef = new CwViewDefinition( "TestView", "TestView description" ); CwView newView = viewRes.createView( viewDef ); // Retrieve and update the properties of the view CwResourceItemProperties viewProps = newView.getProperties(); viewProps.setName( "updatedTestView" ); viewProps.setDescription( "updated TestView description" ); newView.storeProperties(); // Retrieve a view by UID // (this example retrieves the newly created view) CwView fetchedView = (CwView)viewRes.getItemByUid( newView.getUid() ); // List views in the workspace CwView[] views = viewRes.listViews(); // List contents of view (more specifically, the items in the view) CwUid[] items = newView.listItems(); // Delete views CwUid viewUids[] = new CwUid[views.length]; for (int i = 0; i < views.length; i++) { viewUids[i] = views[i].getUid(); } viewRes.deleteViews( viewUids ); // Delete the resource from the workspace // (this deletes all views in the workspace) myWorkspace.deleteResource( viewRes.getUid() );
