Skip Headers

Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-01 |
| Contents

Previous | Next |

# 6 Working with 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 Working with Attachments and File Folders on page 195.

There are several types of 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 extendsjava.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 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: Loading a folder using IAgileSession.getObject()

    //Load the Personal Searches folder
    try {

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

    }
    catch (APIException ex) {

System.out.println(ex);

    }
    try {

The following example shows how to load a folder by specifying its path relative to another folder, in this case the user's Home Folder.

Example: Loading a folder using IFolder.getChild()

    //Get the Home Folder

IFolder homeFolder = m_session.getCurrentUser().getFolder(FolderConstants.TYPE_HOME);

    //Load the Personal Searches subfolder
    try {
    }
    catch (APIException ex) {

IFolder folder = (IFolder)homeFolder.getChild("Personal Searches");

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: Creating a new folder

    //Get an Admin instance

IAdmin admin = m_session.getAdminInstance();

    //Load the Personal Searches folder
    try {
    //Create parameters for a new folder

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

Map params = new HashMap(); params.put(FolderConstants.ATT_FOLDER_NAME, "MyTemporaryQueries"); params.put(FolderConstants.ATT_PARENT_FOLDER, parentFolder);

    //Create a new folder
    }

    catch (APIException ex) {

IFolder folder = (IFolder)session.createObject(IFolder.OBJECT_TYPE, params);

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: Setting the folder type

    //Get an Admin instance

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);

    }
    try {

## 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: Adding objects to a folder

    public void addFolderItem(IFolder folder, Object obj) {

folder.addChild(obj);

}

catch (APIException ex) {

System.out.println(ex);

}

    }
    private String indent(int level) {

### 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: 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: 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 do something with 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: 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());

}

}

    }

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);

    }
    try {

Another way 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: Iterating over folder elements

    //Load the Project X folder

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
    //Write code here to display each folder

Object obj = it.next();

//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.

Example: Deleting a folder

    void deleteFolder(IFolder folder) throws APIException {
    }

folder.delete();