6 Working with Folders

This chapter includes the following:

About Folders
Loading a Folder
Creating a Folder
Setting the Folder Type
Adding and Removing Folder Elements
Getting Folder Elements
Deleting a Folder

6.1 About Folders

An IFolder is a general purpose container used to hold IQuery and IFolder objects as well as any of the main Agile PLM objects (IChange, IItem, IManufacturer, IManufacturerPart, and IPackage). Folders are used to organize queries, or searches.

Note:

A file folder is different from a folder. It has its own interface called the IFileFolder. Files in a file folder holds can be referenced from the Attachments table of other objects. For more information about file folders, see Chapter 13, "Working with Attachments and File Folder Objects."

These are some of the Agile PLM folders:

Private - Folders that are accessible only to the user that created them. Users can create or delete their own Private folders.Public - Folders that are accessible to all Agile PLM users. Only users with the GlobalSearches privilege can create, delete, and modify Public folders.System - Predefined folders that ship with the Agile PLM system. Most users cannot modify or delete System folders.My Bookmarks (or Favorites) - A predefined folder containing each user's bookmarks to Agile PLM objects. You cannot delete the My Bookmarks folder.

Home - The predefined Agile PLM home folder. You cannot delete the Home folder.
Personal Searches - The predefined parent folder for each user's personal searches. You cannot delete the Personal Searches folder.
Recently Visited - A predefined folder containing links to recently visited objects. The SDK does not populate this folder. It is only populated by Client applications. If required, you specify this in your application

Note:

The recently visited folder is only flushed to the database periodically. Therefore, secondary connections like process extensions with portals, or standalone SDK applications will not see the same information that the user's GUI displays.

Report - A folder containing reports. Although you cannot use the Agile API to create, modify, or delete report folders, you can create, modify, or delete them in Agile PLM Clients.

Note:

FolderConstants also includes a constant named TYPE_MODIFIABLE_CONTENTS, but it is currently unused.

Each user's selection of folders may vary. However, every user has a Home folder. From each user's Home folder, you can construct various subfolders and browse public and private queries. To retrieve the Home folder for a user, use the IUser.getFolder(FolderConstants.TYPE_HOME) method.

Folders are subject to the same transactional model as other Agile API objects. If you do not set a transaction boundary for a folder, it is automatically updated as soon as you add anything to, or remove anything from the folder.

IFolder extends java.util.Collection and ITreeNode support all the methods that are provided by those Superinterfaces. That is, you can work with an IFolder object as you would any Java Collection. Methods of ITreeNode allow you to deal with the hierarchical structure of a folder by adding and removing children, getting children, and getting the parent folder.

Interface	Inherited methods
java.util.Collection	add(), addAll(), clear(), contains(), containsAll(), equals(), hashCode(), isEmpty(), iterator(), remove(), removeAll(), retainAll(), size(), toArray()
ITreeNode	addChild(), getChildNode(), getChildNodes(), getParentNode(), removeChild()

6.1.1 Using Level Separation Characters in Folder and Object Names

The SDK supports level separation characters '|'and '/' when naming ITreeNode objects as follows:

'|' in IAgileList object names
'/' in folder names

This feature primarily affects inherited ITreeNode methods shown in the table above. To use these characters, it is necessary to explicitly prefix them with the backslash character ('\').

Note:

To use the backslash character in Java string constants defined in SDK applications, you must specify it twice ('\\').

6.2 Loading a Folder

There are two ways to load a folder:

Use the IAgileSession.getObject() method to specify the full path of a folder.
Use the IFolder.getChild() method to specify the relative path of a subfolder.

Folder and query names are not case-sensitive. Therefore, you can specify a folder path using upper or lower case. For example, to load the Personal Searches folder, you can specify /Personal Searches or /PERSONAL SEARCHES.

The following example shows how to load a folder by specifying the full path to the folder.

Example 6-1 Loading a folder with IAgileSession.getObject()

//Load the Personal Searches foldertry {    IFolder folder = 
      (IFolder)m_session.getObject(IFolder.OBJECT_TYPE, "/Personal Searches");}catch (APIException ex) {    System.out.println(ex);}

The following example loads a folder by specifying its path relative to another folder. In this case, the user's Home Folder.

Example 6-2 Loading a folder with IFolder.getChild()

//Get the Home Foldertry {   IFolder homeFolder =
      m_session.getCurrentUser().getFolder(FolderConstants.TYPE_HOME);

//Load the Personal Searches subfolder   IFolder folder = 
      (IFolder)homeFolder.getChild("Personal Searches");}catch (APIException ex) {      System.out.println(ex);}

6.3 Creating a Folder

To create a folder, use the IAgileSession.createObject() method. When you create a folder, you must specify the folder's name and its parent folder. The following example shows how to create a folder named "MyTemporaryQueries" in the Personal Searches folder.

Example 6-3 Creating a new folder

//Get an Admin instance   try {      IAdmin admin = m_session.getAdminInstance();

//Load the Personal Searches folder      IFolder parentFolder = 
         (IFolder)m_session.getObject(IFolder.OBJECT_TYPE, "/Personal Searches");

//Create parameters for a new folder      Map params = 
         new HashMap(); params.put(FolderConstants.ATT_FOLDER_NAME,            "MyTemporaryQueries"); 
               params.put(FolderConstants.ATT_PARENT_FOLDER, parentFolder);

//Create a new folder      IFolder folder = (IFolder)session.createObject(IFolder.OBJECT_TYPE, params);   }   catch (APIException ex) {        System.out.println(ex);   }

6.4 Setting the Folder Type

By default, all new folders that you create are private folders unless otherwise specified. To change a private folder to a public folder, use the IFolder.setType() method. You must have the GlobalSearches privilege to be able to change a private folder to a public folder.

The two folder type constants you can use to set a folder's type are FolderConstants.TYPE_PRIVATE and FolderConstants.TYPE_PUBLIC. You cannot set a folder to any other folder type.

Example 6-4 Setting the folder type

//Get an Admin instance
try {    IAdmin admin = m_session.getAdminInstance();

//Load the My Cool Searches folder    IFolder folder =        (IFolder)m_session.getObject(IFolder.OBJECT_TYPE,           "/Personal Searches/My Cool Searches");

//Make the folder public 
    folder.setFolderType(FolderConstants.TYPE_PUBLIC);}catch (APIException ex) {    System.out.println(ex);}

6.5 Adding and Removing Folder Elements

An Agile PLM folder can contain IFolder objects (subfolders), IQuery objects, and any kind of dataobject, such as IChange, IItem, IManufacturer, and IManufacturerPart objects. Use the ITreeNode.addChild() method to add objects to a folder.

6.5.1 Adding Folder Elements

The following example shows how to add objects to a table.

Example 6-5 Adding objects to a folder

public void addFolderItem(IFolder folder, Object obj) {   try {      folder.addChild(obj);   }   catch (APIException ex) {
System.out.println(ex);
   }
}

6.5.2 Removing Folder Elements

To remove a single folder element, use the ITreeNode.removeChild() method. To clear all folder elements, use the java.util.Collection.clear() method.

Example 6-6 Removing objects from a Folder

void removeFolderElement(IFolder folder, Object obj) {   try {      folder.removeChild(obj);   } catch (APIException ex) {System.out.println(ex);   }}void clearFolder(IFolder folder) {   try {      folder.clear();   } catch (APIException ex) {      System.out.println(ex);   }}

6.6 Getting Folder Elements

All objects contained in a folder, including subfolders, can be loaded by name. To retrieve an object from a folder, use the IFolder.getChild() method. Remember, the object type for folder elements can vary. Depending on the object, you could be getting a subfolder, a query, or a dataobject, such as an IItem.

Example 6-7 Getting a folder element

public void getFolderChild(IFolder folder, String name) {   try {      IAgileObject object = folder.getChild(name);

//If the object is a query, run it   if (object.getType()==IQuery.OBJECT_TYPE) {      IQuery query = (IQuery)object;      ITable results = query.execute();   }
      //Add code here to modify the query results   }   catch (APIException ex) {      System.out.println(ex);   }}

The following example shows how to use the IFolder.getChildren() method to return an IAgileObject array. In this case, the code checks the object type for each object in the array and then prints the object's name.

Example 6-8 Getting folder children

private void browseFolder(int level, IFolder folder) throws APIException {
   IAdmin admin = 
      m_session.getAdminInstance();   Collection subObjects = 
      folder.getChildNodes();   for (Iterator it = 
      subObjects.iterator();it.hasNext();) {   IAgileObject obj = 
      (IAgileObject)it.next();   System.out.println(indent(level * 4));   switch (obj.getType()) {    case IItem.OBJECT_TYPE:      System.out.println("ITEM: " + obj.getName());      break;    case IFolder.OBJECT_TYPE:      System.out.println("FOLDER: " + obj.getName());      browseFolder(level + 1, (IFolder)obj);      break;    case IQuery.OBJECT_TYPE:      System.out.println("QUERY: " + obj.getName());      break;    default:      System.out.println("UNKNOWN TYPE: " + obj.getType() + ":" + obj.getName());      }   }}private String indent(int level) {   if (level <= 0) {      return "";   }   char c[] = new char[level*2];   Arrays.fill(c, ' ');   return new String(c);}private String indent(int level) {   if (level <= 0) {      return "";   }   char c[] = new char[level*2];   Arrays.fill(c, ' ');   return new String(c);}

Another option to get a folder's children is to iterate over the folder elements, moving from one end of the folder to the other. To create an iterator for an IFolder object, use the java.util.Collection.iterator() method.

Note:

If you need to traverse the folder contents both forward and backward, use the IFolder.getFolderIterator() method to return an ITwoWayIterator object. ITwoWayIterator provides previous(), next(), and skip() methods, among others.

Example 6-9 Iterating over folder elements

//Load the Project X foldertry {   IFolder folder = 
      (IFolder)m_session.getObject(IFolder.OBJECT_TYPE, 
         "/Personal Searches/Project X");

//Create a folder iterator   Iterator it = folder.iterator();   if (it.hasNext()) {

//Get the next folder element      Object obj = it.next();      //Write code here to display each folder element in your program's UI   }} catch (APIException ex) {      System.out.println(ex);}

6.7 Deleting a Folder

To delete a folder, use the IFolder.delete() method. You can delete folders that are empty and that are not predefined Agile PLM system folders (such as the Global Searches and My Inbox folders).

Unlike other dataobjects, folders are not "soft-deleted" the first time you delete them. When you delete a folder, it is removed permanently from the system.

void deleteFolder(IFolder folder) throws APIException { 
      folder.delete();
}