Skip Headers

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

Previous | Next |

# 12 Working with Lists

Many attributes in the Agile PLM system are configured as lists. Agile provides two datatypes to support list fields:

- SingleList - a list in which only one value can be selected.

- MultiList - a list in which multiple values can be selected.

Attributes, properties, and cells can all be lists. The Agile API provides methods for working with lists in the IAgileList interface, a generalized data structure used for all Agile lists. Because IAgileList represents a tree structure of available list values, it extends the ITreeNode interface.

You can use ITreeNode.addChild() to add values to a list. All list values must be unique. After adding a list value, you can prevent its selection by making it obsolete.

## 12.1 List Library

In Agile Java Client, administrators can define custom lists that can be used for Page Two and Page Three list attributes. You can also use the Agile API to define custom lists. The IListLibrary interface provides functionality equivalent to the list library in Agile Java Client. You can use the IAdminList interface to modify the values or properties of a list.

To retrieve the list library, use the IAdmin.getListLibrary() method. You can then use the IListLibrary interface to create new custom lists and work with existing lists. AdminListConstants provide IDs for each list in the list library.

Note The Agile API provides support for several internal Agile lists that are not exposed in the list library in Agile Java Client.

Figure 12-1 List Library

## 12.2 SingleList Lists

A SingleList attribute or cell presents a list from which only one value can be selected. The following figure shows a SingleList cell for Part Types in Agile Web Client.

Figure 12-2 SingleList cell in the Agile Web Client

## 12.3 Cascading Lists

In Agile Java Client, you can configure a SingleList attribute to have multiple hierarchical levels. A list with multiple hierarchical levels is called a cascading list. The following figure shows the Location list, a cascading list, being configured in Agile Java Client. The list has separate levels for continent, country, and city.

Figure 12-3 Configuring a cascading list in the Agile Java Client

Note: The Location list is the only cascading list that ships with Agile PLM. However, you can define your own cascading lists.

## 12.4 MultiList Lists

A MultiList attribute or cell presents a list from which multiple values can be selected. In Agile Web Client, you can select values for a MultiList cell using the Multiple Value Selection dialog, shown in the following figure.

Figure 12-4 Multiple Value Selection window in the Agile Web Client

## 12.5 Methods that Use IAgileList

The IAgileList interface provides the necessary methods to get and set the selected value(s) of a list. The IAgileList interface represents a value object with a tree structure, which is why the interface extends ITreeNode.

The following Agile API methods return an IAgileList object (or an array of IAgileList objects):

- IAdminList.getValues()

- IAdminList.setValues(IAgileList)

- IAttribute.getAvailableValues()

- IAttribute.setAvailableValues(IAgileList)

- IAgileList.getSelection()

- ICell.getAvailableValues()

- IListLibrary.createAdminList(java.util.Map)

- IListLibrary.getAdminList(java.lang.Object)

- IListLibrary.getAdminLists()

- IProperty.getAvailableValues()

The following methods either return an IAgileList or require an IAgileList parameter when the related attribute, cell, or property is a list (the datatype is SingleList or MultiList):

- ICell.getValue() - For SingleList and MultiList cells, the returned Object is an IAgileList.

- ICell.setValue(java.lang.Object value) - For SingleList and MultiList cells, value is an IAgileList.

- IProperty.getValue() - For SingleList and MultiList properties, the returned Object is an IAgileList.

- IProperty.setValue(java.lang.Object value) - For SingleList and MultiList properties, value is an IAgileList.

- IRow.getValue(java.lang.Object cellId) - For SingleList and MultiList cells, the returned Object is an IAgileList.

- IRow.getValues() - For each SingleList or MultiList cell in the row, the returned Map object contains an IAgileList.

- IRow.setValue(java.lang.Object cellId, java.lang.Object value) - If cellID specifies a SingleList or MultiList cell, value is an IAgileList.

- IRow.setValues(java.util.Map map) - For each SingleList or MultiList cell in the row, map contains an IAgileList.

## 12.6 Selecting a List Value

To select a list value, whether it is a SingleList or MultiList list, you must first get the available values for the list. You can then set the selected value. After selecting the list value, save the selection by setting the value for the cell or property.

The following example shows how to change the value of the Visible property of an attribute. The Visible property is a SingleList property with two possible values, No and Yes (or 0 and 1).

Note: You can use IAgileList getAPIName() to get the available values of a list. For information, see Accessing PLM Metadata with APIName Field on page 135.

Example: Changing the Visible property of an attribute

    try {
    // Get the Admin instance

IAdmin admin = m_session.getAdminInstance();

    // Get part  sub-class
    // Get the Admin instance
    // Get the "Page Two.List03" attribute

IAgileClass partClass = admin.getAgileClass(ItemConstants.CLASS_PART);

IAttribute attr = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST03);

    // Get the Visible property
    // Get all available values for the Visible property

IProperty propVisible = attr.getProperty(PropertyConstants.PROP_VISIBLE);

IAgileList values = propVisible.getAvailableValues();

    // Set the selected list value to "Yes"
    // Instead of setting the selection to "Yes", you could also
    // specify the corresponding list value ID, as in the following line:
    // values.setSelection(new Object[] { new Integer(1)});
    // Set the value of the property

values.setSelection(new Object[] { "Yes" });

propVisible.setValue(values);

} catch (APIException ex) {

System.out.println(ex);

    }

When you use the IAgileList.setSelection() method, you can specify String[], Integer[], or IAgileList[] values for the childNodes parameter. When you select a value from the IAgileList object, you can use its String representation or its Integer ID.

To get the currently selected value for a list, use the IAgileList.getSelection() method. For a SingleList cell or property, getSelection() returns an array containing one IAgileList object. For a MultiList cell or property, getSelection() returns an array containing one or more IAgileList objects.

The following example demonstrates how to use several IAgileList methods, including getSelection().

Example: Getting the current list value for the Visible property

    try {

IAdmin admin = m_session.getAdminInstance();

    // Get the Parts class
    // Get the Admin instance
    // Get the "Page Two.List03" attribute

IAgileClass partClass = admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);

IAttribute attr = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST03);

    // Get the Visible property
    // Get the current value of the Visible property

IProperty propVisible = attr.getProperty(PropertyConstants.PROP_VISIBLE);

IAgileList value = (IAgileList)propVisible.getValue();

    // Print the current value
    // Print the list value ID

System.out.println(value); // Prints "Yes"

System.out.println(value.getSelection()[0].getId()); // Prints 1

    // Print the list value
    } catch (APIException ex) {

System.out.println(value.getSelection()[0].getValue()); // Prints "Yes"

System.out.println(ex);

    }

Lists can be reused for several attributes, even for attributes of different classes. The following example reuses the list of available values for a Page Two attribute to set the list of available values for a Page Three list attribute.

Example: Reusing list values for different attributes

    try {
      IAdmin admin = m_session.getAdminInstance();

      // Get the Parts class
      IAgileClass partClass = admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);
      // Get the "Page Two.List01" attribute
      IAttribute attr1 = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST01);
      // Get the "Page Three.List01" attribute
      IAttribute attr2 = partClass.getAttribute(ItemConstants.ATT_PAGE_THREE_LIST01);
      // Set the available values for the list, using values from "Page Two.List01"
      attr2.setAvailableValues(attr1.getAvailableValues());
    } catch (APIException ex) {
      System.out.println(ex);
    }

### 12.6.1 Working with Lifecycle Phase Cells

The Lifecycle Phase attribute is a SingleList datatype. Each subclass in the Agile PLM system can be defined with different lifecycle phases. Therefore, you must get a Lifecycle Phase cell for a subclass before you can retrieve the available values for its list. If you use IAttribute.getAvailableValues() to retrieve the available values for a Lifecycle Phase attribute instead of a subclass-specific cell, the method returns an empty IAgileList object. The following example highlights how to work with Lifecycle Phase cells.

Example: Working with Lifecycle Phase cells

    private static void setLifecyclePhase(IItem item) throws APIException {
    // Get the Lifecycle Phase cell

ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_LIFECYCLE_PHASE);

    // Get available list values for Lifecycle Phase
    // Get the "Page Two.List01" cell
    // Set the value to the second phase

IAgileList values = cell.getAvailableValues();

values.setSelection(new Object[] { new Integer(1)});

cell.setValue(values);

    }

### 12.6.2 Working with Dynamic Lists

The Agile server has both static lists and dynamic lists. Static lists contain a selection of values that do not change at run time. Dynamic lists contain a selection of values that are updated at run time. Users with administrator privileges can modify static lists and add new values and make current values obsolete. Dynamic lists cannot be modified; consequently, the Editable property of dynamic lists is set to No.

Several dynamic lists are capable of containing thousands of value objects. Items, Changes, and Users lists are examples of such lists. Although you can use these lists for Page Two and Page Three fields, you can not enumerate values for these lists.

#### 12.6.2.1 Enumerable and Non-Enumerable Lists

As such, Agile SDK object lists are either enumerable, or non-enumerable. If a specific list is enumerable, you can read the contents of that list. If it is non-enumerable, you cannot access the list directly. For non-enumerable lists, query the Agile class that the object list uses to get the objects that are referenced by the list. The enumeration property for an object is hard coded on the server and cannot be changed.

To determine if the values for a dynamic list can be enumerated, use IAgileList.getChildNodes() as shown in the following example. If getChildNodes() returns null, the list values cannot be enumerated. However, this does not prevent you from selecting a value for the list.

Example: Checking whether values for a dynamic list are enumerable

    private void setPageTwoListValue(IItem item) throws APIException {

ICell cell = item.getCell(CommonConstants.ATT_PAGE_TWO_LIST01);

    // Get available values for the list
    // Get the List property
    // If the list cannot be enumerated, set the selection to the current user

IAgileList values = cell.getAvailableValues();

if (values.getChildNodes() == null) {

values.setSelection(new Object[]{m_session.getCurrentUser()});

cell.setValue(values);

}

    }
    // Get the "Page Two.Multilist01" cell

private void setPageTwoMultilistValue(IItem item) throws APIException {

ICell cell = item.getCell(CommonConstants.ATT_PAGE_TWO_MULTILIST01);

    // Get available values for the list
    // If the list cannot be enumerated, set the selection to an array of users

IAgileList values = cell.getAvailableValues();

if (values.getChildNodes() == null) {

IAgileClass cls = cell.getAttribute().getListAgileClass();

if (cls != null) {

IUser user1 = (IUser)m_session.getObject(cls, "hhawkes");

IUser user2 = (IUser)m_session.getObject(cls, "ahitchcock");

IUser user3 = (IUser)m_session.getObject(cls, "jhuston");

Object[] users = new Object[] {user1, user2, user3};

values.setSelection(users);

cell.setValue(values);

}

}

    }

#### 12.6.2.2 Directly Checking if Contents of the List is an Enumerable Set

SDK exposes the following API to directly determine if the contents of a list is enumerable:

    boolean isEnumeratable ( ) throws APIException;

This method determines if the contents of the IAgileList are enumerable and is a convenient alternative to using IAgileList.getChildren() which requires accessing all child values of the list. This method returns a Boolean true if the list is enumerable. That is, it has an accessible child list, and a Boolean false if otherwise.

#### 12.6.2.3 Non-Enumerable PG&C Lists

The following PG&C lists that were enumerable in earlier releases of the SDK, are no longer enumerable in this release.

- Declarations

- Substances

- Specifications

- Part Families

- Part Families Commodities

## 12.7 Setting the Maximum Value Displayed by a List - 933

Using PLM's Java Client, an authorized user can view and set the number of List rows by selecting Admin > Server Settings > Preferences and selecting the Maximum List Values Displayed preference.

The new PropertyConstants PROP_MAXIMUM_LIST_VALUES_DISPLAYED cc

provide the option to set the maximum value that a List can display in Administrator Preferences. That is, when the maximum value exceeds this set limit, an error message displays the maximum value set in the Preferences, instead of displaying the integer 250 as was done in prior releases.

It just added a PropertyConstants "PROP_MAXIMUM_LIST_VALUES_DISPLAYED".

So you can get/set preference "Max List Values Displayed" value using this property constant.

For example:

INode preferences = session.getAdminInstance().getNode(NodeConstants.NODE_PREFERENCES);

IProperty prop = preferences.getProperty(PropertyConstants.PROP_MAXIMUM_LIST_VALUES_DISPLAYED);

System.out.println("Current Value: " + prop.getValue());

prop.setValue("666");

System.out.println("New Value: " + prop.getValue());

## 12.8 Selecting a List from the List Library

The IListLibrary interface enables working with the library of Agile lists. You can load an existing list, or create a new one. To load an existing list, use IListLibrary.getAdminList(). You can specify the string name of a list, such as "Disposition." You can also specify a list, by its ID, or by an AdminListConstants, such as LIST_DISPOSITION_SELECTION. Before you attempt to use a list from the list library, make sure the list is enabled.

The following example shows how to configure a Page Two list attribute to use a list called Users.

Example: Configuring an attribute to use an Agile list

    try {
    // Get the Admin instance

IAgileList values = null;

IAdmin admin = m_session.getAdminInstance();

    // Get the List Library
    // Get the Parts class

IListLibrary listLib = admin.getListLibrary();

IAgileClass partClass = admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);

    // Get the "Page Two.List01" attribute
    // Make the list visible

IAttribute attr = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST01);

IProperty propVisible = attr.getProperty(PropertyConstants.PROP_VISIBLE);

values = propVisible.getAvailableValues();

values.setSelection(new Object[] { "Yes" });

propVisible.setValue(values);

    // Change the name of the attribute to "Project Manager"

IProperty propName = attr.getProperty(PropertyConstants.PROP_NAME);

propName.setValue("Project Manager");

    // Get the list property
    // Use the Users list from the list library.

IProperty propList = attr.getProperty(PropertyConstants.PROP_LIST);

IAdminList users = listLib.getAdminList(AdminListConstants.LIST_USER_OBJECTS);

if (users != null ) {

if (users.isEnabled()) {

propList.setValue(users);

} else {

System.out.println("Users list is not enabled.");

}

}

// Specify the Default Value to the current user

IProperty propDefValue = attr.getProperty(PropertyConstants.PROP_DEFAULTVALUE);

values = propDefValue.getAvailableValues();

values.setSelection(new Object[]{m_session.getCurrentUser()});

propDefValue.setValue(values);

    } catch (APIException ex) {
    }

System.out.println(ex);

When you select a user-defined list using IListLibrary.getAdminList(), you can specify the list by name or ID. All list names must be unique. The following example shows how to select an Agile list called Colors.

Example: Selecting a list named Colors

    private void selectColorsList(IAttribute attr, IListLibrary m_listLibrary) throws APIException {

IProperty propList = attr.getProperty(PropertyConstants.PROP_LIST);

    // Use the Colors list
    // Get the Admin instance

IAdminList listColors = m_listLibrary.getAdminList("Colors");

if (listColors != null ) {

if (listColors.isEnabled()) {

propList.setValue(listColors);

} else {

System.out.println("Colors list is not enabled.");

}

}

    }

## 12.9 Creating Custom Lists

The Agile API lets you modify list attributes for different classes and configure custom list attributes for Page Two and Page Three. You can customize these list attributes to create simple lists or multilists. You can also configure a list to be cascading, that is, have multiple levels.

In Agile Java Client, administrators can configure a library of custom lists by choosing Admin > Data Settings > Lists. In the Agile API, the IListLibrary interface provides functionality equivalent to Admin > Data Settings > Lists. The IAdminList interface provides functionality for configuring and customizing each list.

### 12.9.1 Creating a Simple List

To create a new list, use the IListLibrary.createAdminList() method, which takes a map parameter. The map that you pass with createAdminList() must contain values for the following IAdminList fields:

- ATT_NAME - the String name of the list. This is a required field. The list name must be unique.

- ATT_DESCRIPTION - the String description of the list. This is an optional field; the default value is an empty string.

- ATT_ENABLED - a Boolean value specifying whether the list is enabled. This is an optional field; the default value is false.

- ATT_CASCADED - a Boolean value specifying whether the list contains multiple levels. This is an optional field; the default value is false. The ATT_CASCADED value cannot be changed after the list is created.

Once the list is created, you can use the IAdminList interface to enable or disable the list and set values for it.

The following example shows how to create a new list called Colors. This list is a simple list with only one level.

Example: Creating a simple list

    try {

IAdmin admin = m_session.getAdminInstance();

    // Get the List Library
    IAgileList list = listColors.getValues(); //The list is empty at this point.
    // Create a new Admin list

IListLibrary listLib = admin.getListLibrary();

HashMap map = new HashMap();

String name = "Colors";

map.put(IAdminList.ATT_NAME, name);

map.put(IAdminList.ATT_DESCRIPTION, name);

map.put(IAdminList.ATT_ENABLED, new Boolean(true));

map.put(IAdminList.ATT_CASCADED, new Boolean(false));

IAdminList listColors = listLib.createAdminList(map);

    // Add values to the list

list.addChild("Black");

list.addChild("Blue");

list.addChild("Green");

list.addChild("Purple");

list.addChild("Red");

list.addChild("White");

listColors.setValues(list);

    } catch (APIException ex) {
    // Get the Admin instance
    }

System.out.println(ex);

Lists that contain String values are case-sensitive. This means that a list can contain uppercase, lowercase, and mixed-case variations of the same value, which may not be desirable. For example, the following code snippet adds three variations of each color value to the Colors list.

Example: Adding case-sensitive values to a list

    IAgileList list = listColors.getValues(); //The list is empty at this point.

list.addChild("Black");

list.addChild("BLACK");

list.addChild("black");

list.addChild("Blue");

list.addChild("BLUE");

list.addChild("blue");

list.addChild("Green");

list.addChild("GREEN");

list.addChild("green");

list.addChild("Purple");

list.addChild("PURPLE");

list.addChild("purple");

list.addChild("Red");

list.addChild("RED");

list.addChild("red");

list.addChild("White");

list.addChild("WHITE");

list.addChild("white");

### 12.9.2 Automatically Creating New Lists by Modifying Existing Lists

Each list attribute must reference an Agile list for its values. If you retrieve an Agile list and modify its values without saving the list and then use those values for a list attribute, the Agile API automatically creates a new list. In the following example, the Colors list is retrieved, but before it is used to populate the values for a list field a new value, "Violet," is added to the list. When IAttribute.setAvailableValues() is called, a new list is created.

Note: Lists that are created automatically by the Agile API have a prefix "SDK" followed by a random number. You can rename such lists, if you prefer.

Example: Creating a new list automatically by modifying an existing list

    try {
    // Get the Colors list

IAdminList listColors = m_listLibrary.getAdminList("Colors");

    // Get the Parts class
    // Get the "Page Two.List01" attribute

IAgileClass partsClass = admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);

IAttribute attr = partsClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST01);

    // Get the color values
    // Add a new color

IAgileList values = listColors.getValues();

values.addChild("Violet");

    // Set the available list values for "Page Two.List01". Because the list // was modified, a new AdminList is created automatically.
    } catch (APIException ex) {

attr.setAvailableValues(values);

System.out.println(ex);

    }

### 12.9.3 Creating a Cascading List

A cascading list is a list with multiple levels. You can configure SingleList attributes and cells using a cascading list instead of a simple list.

Note: Once you set a list to be cascading, you can't change it to a simple list. You cannot change the value of IAdminList.ATT_CASCADED after the list is created.

The following example shows how to create a new cascading list called "Field Office." The list has two levels.

Important: When setting level names for cascading lists, always start with the index 0 for the first level and increment the index subsequent levels as shown in the following two examples below.

Example: Creating a cascading list

    try {

IAdmin admin = m_session.getAdminInstance();

    // Get the List Library
    IAgileList list = listFO.getValues(); // The list is empty at this point.
    // Create a new Admin list

IListLibrary listLib = admin.getListLibrary();

HashMap map = new HashMap();

String name = "Field Office";

map.put(IAdminList.ATT_NAME, name);

map.put(IAdminList.ATT_DESCRIPTION, name);

map.put(IAdminList.ATT_ENABLED, new Boolean(true));

map.put(IAdminList.ATT_CASCADED, new Boolean(true));

IAdminList listFO = listLib.createAdminList(map);

    // Get the empty list
    // Add the list of countries

IAgileList list = listFO.getValues();

IAgileList india = (IAgileList)list.addChild("India");

IAgileList china = (IAgileList)list.addChild("China");

IAgileList usa = (IAgileList)list.addChild("USA");

IAgileList australia = (IAgileList)list.addChild("Australia");

    // Add the list of cities

india.addChild("Bangalore");

china.addChild("Hong Kong");

china.addChild("Shanghai");

china.addChild("Suzhou");

usa.addChild("San Jose");

usa.addChild("Milpitas");

usa.addChild("Seattle");

usa.addChild("Jersey City");

australia.addChild("Sidney");

    // Save the list values
    // Set level names starting with index 0 for level 1.

listFO.setValues(list);

list.setLevelName(0, "Field Office Country");

list.setLevelName(1, "Field Office City");

    } catch (APIException ex) {
    }

System.out.println(ex);

In cascading lists, level names used by the list must be unique and you cannot share them between lists. The level names are stored internally, but Agile Java Client and Web Client currently don't display them. The level names are needed only if you want to show them in a cascading list UI that you created.

After you call the IAdminList.setValues() method, a valid ID is assigned to each list value. Only leaf nodes, that is, nodes on the lowest level of a cascading list, have valid IDs. In the previous example, the city nodes are leaf nodes. All other nodes have a null ID. You can use the ID to set the selection of the IAgileList object.

You can add a list value and its parent nodes in one statement instead of adding the parent node and then its subnodes. Use the | character to separate nodes, which represent levels, in the string. The following example replaces a portion of the code in the previous example; it shows how to add the same list values as in the previous example, but using fewer lines of code.

Example: Adding parent nodes and subnodes to a cascading list

    // Get the list values
    // Add nodes

list.addChild("India|Bangalore");

list.addChild("Hong Kong|Hong Kong");

list.addChild("China|Suzhou");

list.addChild("USA|San Jose");

list.addChild("USA|Milpitas");

list.addChild("USA|Jersey City");

list.addChild("Australia|Sidney");

// Save the list values

listFO.setValues(list);

    // Set level names
    // Get the Parts class

list.setLevelName(0, "Field Office Country");

list.setLevelName(1, "Field Office City");

### 12.9.4 Creating a Criteria-Based List

Criteria-based lists are dynamic lists whose values are defined by the criteria selected from the Agile Criteria library. These lists are created in Java Client's Create List dialog by selecting the "Dynamic" List Type in the drop-down list which opens the Agile Criteria library to select the applicable Criteria.

Figure 12-5 Creating criteria-based lists in Java Client

Agile SDK supports creating, loading, and modifying Criteria-based lists by exposing the necessary APIs to:

1. Get the Criteria

2. Create the Criteria-based list

3. Load the Criteria-based list

4. Replace the Criteria-based list

The following examples use the respective APIs to perform these tasks.

Example: Getting the Criteria from the Agile Criteria library

IListLibrary library = m_admin.getListLibrary();

INode lib = m_admin.getNode(NodeConstants.NODE_CRITERIA_LIBRARY);

ICriteria criteria = (ICriteria)lib.getChild("All Change Orders");

Example: Creating the Criteria-based list

HashMap params = new HashMap();

String name = "SDKlist" + System.currentTimeMillis();

params.put(IAdminList.ATT_APINAME, name.toUpperCase());

params.put(IAdminList.ATT_NAME, name.toUpperCase());

params.put(IAdminList.ATT_DESCRIPTION, name.toLowerCase());

params.put(IAdminList.ATT_ENABLED, true);

params.put(IAdminList.ATT_CRITERIA, criteria);

ICriteriaBasedList list = (ICriteriaBasedList)library.createDynamicAdminList(params);

System.out.println("Created list: "+list.getName());

System.out.println("Criteria: "+((ICriteriaBasedList)list).getCriteria().toString());

Example: Loading the Criteria-based list

ICriteriaBasedList list = (ICriteriaBasedList)m_admin.getListLibrary().getAdminList(name.toUpperCase());

System.out.println("Loaded list: "+list.getName());

Example: Replacing the Criteria - Modifying the Criteria-based list

ICriteria criteria = (ICriteria)lib.getChild("All Designs");

list.setCriteria(criteria);

System.out.println("New Criteria: "+((ICriteriaBasedList)list).getCriteria().toString());

## 12.10 Checking the Data Type of a List

A list can contain objects of any Agile datatype. Therefore, before getting or setting a list value, you should determine the data type of objects in the list. If you are working with a cascading list, the data type can vary with each level. There are several ways to determine the data type of a list:

- For predefined lists in the List Library, use IAdminList.getListDataType() to get the data type.

- For SingleList and MultiList attributes that have only one list level, use the IAttribute.getListDataType() method to get the data type for the entire list.

- For a level within a cascading list, use the IAgileList.getLevelType() method to get the data type for a particular level.

Example: Checking the data type of a list

    public void setDefaultValue() throws APIException {

IAgileClass partClass = m_admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);

    // Get the "Page Two.List01" attribute
    list.addChild("RED");

IAttribute attr = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST01);

switch (attr.getListDataType()) {

case DataTypeConstants.TYPE_OBJECT:

//Add code here to handle Object values

break;

case DataTypeConstants.TYPE_STRING:

    //Add code here to handle String values

break;

default:

    //Add code here to handle other datatypes

}

    }

## 12.11 Renaming and Removing List Values - 9.3.3

The SDK provides the following methods to rename String element entries, or remove an entry in an Agile list:

- The IAgileList.setValue(Object) method to modify String list element entries in an Agile Admin list.

Note: This method only applies to String values. You can only use this method to modify String entries and not object entries.

- The IAgileList.clear() and ITree.removeChild(Object) methods to remove any Agile list entry that is not restricted by the applicable business rules.

The following example uses these methods to modify and clear valuesn an Agile list.

Renaming and removing Admin list entries

    public void exampleClearList() throws Exception {

IAdmin admin = m_session.getAdminInstance();

IListLibrary listLibrary = admin.getListLibrary();

HashMap map = new HashMap();

String name = "Color";

String desc = "Example";

map.put(IAdminList.ATT_NAME, name);

map.put(IAdminList.ATT_DESCRIPTION, desc);

map.put(IAdminList.ATT_ENABLED, new Boolean(true));

map.put(IAdminList.ATT_CASCADED, new Boolean(false));

IAdminList newList = listLibrary.createAdminList(map);

    IAgileList list = newList.getValues();
    list.addChild("GREEN");
    list.addChild("BLUE");
    newList.setValues(list);
    list = newList.getValues();

    // Removing the selection

IAgileList agList = (IAgileList)list.getChild("BLUE");

Object errorCode = null;

try {

list.removeChild(agList);

}catch(APIException e){

errorCode = e.getErrorCode();

}

// Clearing the list

list = newList.getValues();

list.clear();

newList.setValues(list);

// Clean up

newList.delete();

    }
    // Get the Admin instance

### 12.11.1 Adding a Value to a List

The following example shows how to add several values to a list. Before adding a value to a list, use the ITreeNode.getChildNode() method to make sure the value doesn't already exist.

Example: Adding values to a list

    private static void updateProductLinesList() throws APIException {

IAdmin admin = m_session.getAdminInstance();

    // Get the List Library
    public void setObsolete(IAgileList list, String value) throws APIException {
    // Get the Product Lines list

IListLibrary listLib = admin.getListLibrary();

IAdminList listProdLine = listLib.getAdminList("Product Line");

    // Add values to the list

IAgileList listValues = listProdLine.getValues();

addToList(listValues, "Saturn");

addToList(listValues, "Titan");

addToList(listValues, "Neptune");

listProdLine.setValues(listValues);

    }

### 12.11.2 Making List Values Obsolete

You can prevent the selection of a list value by making the list entry obsolete. However, when you invoke the IProperty.getAvailableValues() method, the returned IAgileList object can include obsolete list values. This is due to the fact that when the list value is marked obsolete, the server continues to maintain the value in its obsolete list values for existing objects that use these values.

The following example shows how to check whether a list value is obsolete and how to make it obsolete.

Example: Making a list value obsolete

    public void checkIfObsolete(IAgileList list) throws APIException {

if (list != null ) {

if (list.isObsolete() == false) {

System.out.println(list.getValue());

}

}

    }

if (list != null ) {

list.setObsolete(true);

System.out.println(list.getValue() + " is now obsolete.");

}

    }
    public void disableList(IAdminList list) throws APIException {

### 12.11.3 Setting the List Name and Description

To create a list, you must specify a unique name for it. Therefore, when you use IListLibrary.createAdminList(), you must pass a value for the IAdminList.ATT_NAME field. Other IAdminList fields, such as ATT_DESCRIPTION, are optional. After the list is created, you can modify it's name and description. The following example shows how to set the name and description of a list.

Example: Setting the list name and description

    try {

IAdminList list = m_listLibrary.getAdminList("Packaging Styles");

list.setName("Packaging Color Codes");

list.setDescription("Color codes for product packaging");

    } catch (APIException ex) {
    }

System.out.println(ex);

### 12.11.4 Setting Level Names for a Cascading List

Like list names, the level names for a list must be unique. You can't reuse the level name used by another cascading list. To check if the list with a given name already exists, use IListLibrary.getAdminList(). Use one of the following methods to set the level name of a cascading list:

- IAgileList.setLevelName(int, String) - Sets the level name for a specified level.

- IAgileList.setLevelName(String) - Sets the level name of the current level.

For an example showing how to set the level names of a cascading list, see Creating a Cascading List on page 184.

Note: Level names for cascading lists are not displayed in Agile Java Client or Web Client. However, you can choose to display them in Clients you create with the Agile SDK.

### 12.11.5 Enabling or Disabling a List

When you create a custom list, you can use the IAdminList.ATT_ENABLED field to specify whether it's enabled. If you omit this field, the list is disabled by default. The following example shows how to enable and disable a list after it has been created.

Example: Enabling and disabling a list

    public void enableList(IAdminList list) throws APIException {

list.enable(true);

System.out.println("List " + list.getName() + " enabled.");

    }

list.enable(false);

System.out.println("List " + list.getName() + " disabled.");

    }
    public void deleteList(IAdminList list) throws APIException {

### 12.11.6 Deleting a List

If a list is not read-only and is not currently being used by an Agile dataobject, you can delete it. Otherwise, the IAdminList.delete() method throws an exception. Once you delete a list, it is removed permanently. You cannot undo the deletion.

The following example shows how to delete a list.

    Deleting a list

    // Make sure the list is not read-only

if (!list.isReadOnly()) {

    // Delete the list
    list.addChild("RED");

list.delete();

System.out.println("List " + list.getName() + " deleted.");

} else {

System.out.println("List " + list.getName() + " is read-only.");

}

    }

### 12.11.7 Renaming and Removing List Values - 9.3.3

The SDK provides the following methods to rename String element entries, or remove an entry in an Agile list:

- The IAgileList.setValue(Object) method to modify String list element entries in an Agile Admin list.

Note: This method only applies to String values. You can only use this method to modify String entries and not object entries.

- The IAgileList.clear() and ITree.removeChild(Object) methods to remove any Agile list entry that is not restricted by the applicable business rules.

The following example uses these methods to modify and clear valuesn an Agile list.

Renaming and removing Admin list entries

    public void exampleClearList() throws Exception {

IAdmin admin = m_session.getAdminInstance();

IListLibrary listLibrary = admin.getListLibrary();

HashMap map = new HashMap();

String name = "Color";

String desc = "Example";

map.put(IAdminList.ATT_NAME, name);

map.put(IAdminList.ATT_DESCRIPTION, desc);

map.put(IAdminList.ATT_ENABLED, new Boolean(true));

map.put(IAdminList.ATT_CASCADED, new Boolean(false));

IAdminList newList = listLibrary.createAdminList(map);

    IAgileList list = newList.getValues();
    list.addChild("GREEN");
    list.addChild("BLUE");
    newList.setValues(list);
    list = newList.getValues();

    // Removing the selection

IAgileList agList = (IAgileList)list.getChild("BLUE");

Object errorCode = null;

try {

list.removeChild(agList);

}catch(APIException e){

errorCode = e.getErrorCode();

}

// Clearing the list

list = newList.getValues();

list.clear();

newList.setValues(list);

// Clean up

newList.delete();

    }
    private String indent(int level) {

## 12.12 Printing Contents of IAgileList Objects

When working with an IAgileList object, particularly one with several levels, it's helpful to print the entire hierarchy of the list. The following code prints the list nodes contained within an IAgileList object.

Example: Printing list nodes in an IAgileList object

    private void printList(IAgileList list, int level) throws APIException {

if (list != null ) {

System.out.println(indent(level*4) + list.getLevelName() + ":" +

list.getValue() + ":" + list.getId());

Object[] children = list.getChildren();

if (children != null) {

for (int i = 0; i < children.length; ++i) {

printList((IAgileList)children[i], level + 1);

}

}

}

    }

if (level <= 0) {

return "";

}

char c[] = new char[level*2];

Arrays.fill(c, ' ');

return new String(c);

    }