| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-02 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-02 |
|
Previous |
Next |
This chapter includes the following:
About Lists
Selecting a List Value
Setting the Maximum Value Displayed by a List
Creating Custom Lists
Checking the Data Type of a List
Renaming and Removing List Values
Printing Contents of IAgileList Objects
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.
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 IAdminList 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. |
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.
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.
|
Note: The Location list is the only cascading list that ships with Agile PLM. However, you can define your own cascading 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.
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.
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 Chapter 8, "Accessing PLM Metadata with APIName Field." |
Example 12-1 Changing the Visible property of an attribute
try {// Get the Admin instance IAdmin admin = m_session.getAdminInstance();
// Get part sub-class IAgileClass partClass = admin.getAgileClass(ItemConstants.CLASS_PART);
// Get the "Page Two.List03" attribute
IAttribute attr = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST03);
// Get the Visible property IProperty propVisible = attr.getProperty(PropertyConstants.PROP_VISIBLE);
// Get all available values for the Visible property
IAgileList values = propVisible.getAvailableValues();
// Set the selected list value to "Yes" values.setSelection(new Object[] { "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
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, IAgileList 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 12-2 Getting the current list value for the Visible property
try {
// Get the Admin instance
IAdmin admin = m_session.getAdminInstance();
// Get the Parts class
IAgileClass partClass = admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);
// Get the "Page Two.List03" attribute
IAttribute attr = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST03);
// Get the Visible property
IProperty propVisible = attr.getProperty(PropertyConstants.PROP_VISIBLE);
// Get the current value of the Visible property
IAgileList value = (IAgileList)propVisible.getValue();
// Print the current value
System.out.println(value); // Prints "Yes"
// Print the list value ID
System.out.println(value.getSelection()[0].getId()); // Prints 1
// Print the list value
System.out.println(value.getSelection()[0].getValue()); // Prints "Yes"
} catch (APIException ex) {
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 12-3 Reusing list values for different attributes
try {// Get the Admin instance 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" attributeIAttribute 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);}
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 12-4 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 IAgileList values = cell.getAvailableValues();// Set the value to the second phase values.setSelection(new Object[] { new Integer(1)}); cell.setValue(values);}
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.
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 12-5 Checking the values for a dynamic list for enumerability
private void setPageTwoListValue(IItem item) throws APIException {// Get the "Page Two.List01" cell ICell cell = item.getCell(CommonConstants.ATT_PAGE_TWO_LIST01);
// Get available values for the list IAgileList values = cell.getAvailableValues();// If the list cannot be enumerated, set the selection to the current user if (values.getChildNodes() == null) { values.setSelection(new Object[]{m_session.getCurrentUser()}); cell.setValue(values); }} private void setPageTwoMultilistValue(IItem item) throws APIException {// Get the "Page Two.Multilist01" cell
ICell cell = item.getCell(CommonConstants.ATT_PAGE_TWO_MULTILIST01);
// Get available values for the list IAgileList values = cell.getAvailableValues();
// If the list cannot be enumerated, set the selection to an array of users 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);
}
}}
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.
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 provides 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.
With the new PropertyConstants PROP_MAXIMUM_LIST_VALUES_DISPLAYED, 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());
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 12-6 Configuring an attribute to use an Agile list
try { IAgileList values = null;
// Get the Admin instance IAdmin admin = m_session.getAdminInstance();
// Get the List Library IListLibrary listLib = admin.getListLibrary();
// Get the Parts class IAgileClass partClass = admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);
// Get the "Page Two.List01" attribute IAttribute attr = partClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST01);
// Make the list visible 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 IProperty propList = attr.getProperty(PropertyConstants.PROP_LIST);// Use the Users list from the list library.
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 12-7 Selecting a list named Colors
private void selectColorsList(IAttribute attr,
IListLibrary m_listLibrary) throws APIException {// Get the List propertyIProperty propList = attr.getProperty(PropertyConstants.PROP_LIST);
// Use the Colors listIAdminList listColors = m_listLibrary.getAdminList("Colors"); if (listColors != null ) { if (listColors.isEnabled()) {propList.setValue(listColors); } else {System.out.println("Colors list is not enabled."); } }}
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.
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 12-8 Example: Creating a simple list
try {// Get the Admin instance IAdmin admin = m_session.getAdminInstance();// Get the List Library IListLibrary listLib = admin.getListLibrary();// Create a new Admin list 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 IAgileList list = listColors.getValues();
//The list is empty at this point. list.addChild("Black"); list.addChild("Blue"); list.addChild("Green"); list.addChild("Purple"); list.addChild("Red"); list.addChild("White"); listColors.setValues(list);} catch (APIException ex) { 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 12-9 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");
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 12-10 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 IAgileClass partsClass = admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);// Get the "Page Two.List01" attribute IAttribute attr = partsClass.getAttribute(ItemConstants.ATT_PAGE_TWO_LIST01);// Get the color values IAgileList values = listColors.getValues();// Add a new color values.addChild("Violet");// Set the available list values for "Page Two.List01". Because the list
// was modified, a new AdminList is created automatically. attr.setAvailableValues(values);} catch (APIException ex) { System.out.println(ex);}
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 12-11 Creating a cascading list
try {// Get the Admin instance IAdmin admin = m_session.getAdminInstance();// Get the List Library IListLibrary listLib = admin.getListLibrary();// Create a new Admin list 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 IAgileList list = listFO.getValues();// Add the list of countries 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 listFO.setValues(list);// Set level names starting with index 0 for level 1. 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 12-12 Adding parent nodes and subnodes to a cascading list
// Get the list values IAgileList list = listFO.getValues(); // The list is empty at this point.// 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 valueslistFO.setValues(list);// Set level nameslist.setLevelName(0, ”Field Office Country”);list.setLevelName(1, ”Field Office City”);
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.
Agile SDK supports creating, loading, and modifying Criteria-based lists by exposing the necessary APIs to:
Get the Criteria
Create the Criteria-based list
Load the Criteria-based list
Replace the Criteria-based list
The following examples use the respective APIs to perform these tasks.
Example 12-13 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 12-14 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());
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 12-17 Checking the data type of a list
public void setDefaultValue() throws APIException {// Get the Parts class IAgileClass partClass = m_admin.getAgileClass(ItemConstants.CLASS_PARTS_CLASS);// Get the "Page Two.List01" attribute 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
}}
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 values of an Agile list.
Example 12-18 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("RED"); 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();}
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 12-19 Adding values to a list
private static void updateProductLinesList() throws APIException {// Get the Admin instance IAdmin admin = m_session.getAdminInstance();// Get the List LibraryIListLibrary listLib = admin.getListLibrary();// Get the Product Lines list IAdminList listProdLine = listLib.getAdminList("Product Line");// Add values to the list IAgileList listValues = listProdLine.getValues(); addToList(listValues, "Saturn"); addToList(listValues, "Titan"); addToList(listValues, "Neptune");vlistProdLine.setValues(listValues);}
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 12-20 Making a list value obsolete
public void checkIfObsolete(IAgileList list) throws APIException { if (list != null ) { if (list.isObsolete() == false) { System.out.println(list.getValue()); } }}public void setObsolete(IAgileList list, String value) throws APIException { if (list != null ) { list.setObsolete(true);System.out.println(list.getValue() + " is now obsolete."); }}
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.
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."
|
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. |
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 12-22 Enabling and disabling a list
public void enableList(IAdminList list) throws APIException { list.enable(true); System.out.println("List " + list.getName() + " enabled.");}
public void disableList(IAdminList list) throws APIException { list.enable(false); System.out.println("List " + list.getName() + " disabled.");}
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.
Example 12-23 Deleting a list
public void deleteList(IAdminList list) throws APIException {// Make sure the list is not read-onlyif (!list.isReadOnly()) {
// Delete the list list.delete(); System.out.println("List " + list.getName() + " deleted."); } else {System.out.println("List " + list.getName() + " is read-only."); }
}
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 12-24 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); } } }}private String indent(int level) { if (level <= 0) { return ""; } char c[] = new char[level*2]; Arrays.fill(c, ' '); return new String(c);
}
|
 Copyright © 2010, 2014, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|