| 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 Data Cells
Data Types
Checking the Discovery Privilege of the User
Checking if the Cell is a Read-Only Cell
Getting Values
Setting Values
Getting and Setting List Values
Using Reference Designator Cells
An ICell object is a data field for an Agile PLM object that you have loaded or created in your program. A cell can correspond to a field on a tab in Agile Web Client or a single cell on a table. The ICell object consists of several properties that describe the current state of a cell. Most of the data manipulation your Agile API programs perform will involve changes to the value or properties of cells.
The type of objects associated with the getValue() and setValue() methods depends on the cell's data type. The table below lists the object types of cell values for getValue() and setValue() methods.
| DataTypeConstants | Object type associated with getValue and setValue |
|---|---|
| TYPE_DATE | Date |
| TYPE_DOUBLE | Double |
| TYPE_INTEGER | Integer |
| TYPE_MONEY | Money |
| TYPE_MULTILIST | IAgileList |
| TYPE_OBJECT | Object |
| TYPE_SINGLELIST | IAgileList |
| TYPE_STRING | String |
| TYPE_TABLE | Table |
|
Note: There are other Agile PLM datatypes, such as TYPE_WORKFLOW, but they are not used for cell values. |
The Discovery privilege is the most basic Agile PLM privilege. It allows users to find if an object exists. If you do not have the Discovery privilege for an object, you won't be able to view that object.
For example, if a user does not have the Discovery privilege for Manufacturer Parts, your program will not allow the user to view several cells on the Manufacturers table of an item. You can use the ICell.hasDiscoveryPrivilege() method to check if the user has the Discovery privilege for a particular cell, as shown in the following example.
|
Note: When you get the value for a cell for which you don't have the Discovery privilege, the Agile API returns a null string (""). This behavior is different with other Agile PLM Clients. For example, Agile Web Client displays the value "No Privilege" when you try to view a field for which you don't have the necessary viewing privileges. |
Example 5-1 Checking User Discovery privilege
Object v;Integer attrID =
ItemConstants.ATT_MANUFACTURERS_MFR_NAME;
// Get the Manufacturers table
try { ITable aml = item.getTable(ItemConstants.TABLE_MANUFACTURERS);
// Get the first row of the Manufacturers table
IIterator iterator = aml.getTableIterator(); if (iterator.hasNext()) { IRow amlRow = (IRow)iterator.next();}
// Get the value for the Mfr. Name field. If the user does not have Discovery
// privilege, the value is a null String.
Integer attrID =
ItemConstants.ATT_TITLE_BLOCK_NUMBER; v = amlRow.getValue(attrID); txtMfrName.setText(v.toString());
// If the user does not have the Discovery privilege// for the cell, make its text color red.ICell cell = amlRow.getCell(attrID); if (cell.hasDiscoveryPrivilege()==false) {txtMfrName.setForeground(Color.red); }} catch (APIException ex) { System.out.println(ex);}
Roles and privileges assigned to a user by Agile PLM administrators, determine the level of access the user has to Agile PLM objects and their underlying data. For example, users with only ReadOnly privileges can view Agile PLM objects but not modify them.
Whenever your program displays a value from a cell, you should check whether the cell is read-only for the current user. If it is, your program must not allow the user to edit the value. If a user tries to set a value for a read-only cell, the Agile API throws an exception.
Example 5-2 Checking whether a field is a read-only field
// ID for "Title Block.Description"// Set the value for the Description text field.try { Integer attrID =
ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION; txtDescription.setText(item.getValue(attrID).toString());
// Get the ICell object for "Title Block.Description"// If the cell is read-only, disable the cell ICell cell = item.getCell(attrID); if (cell.isReadOnly()) { txtDescription.setEnabled(false); txtDescription.setBackground(Color.lightGray);} else { txtDescription.setEnabled(true); txtDescription.setBackground(Color.white); }} catch (APIException ex) { System.out.println(ex);}
The following table lists Agile API methods for getting values for cells.
| Method | Description |
|---|---|
| ICell.getValue() | Gets a cell value |
| IRow.getValue() | Gets a cell value contained within a row |
| IRow.getValues() | Gets all cell values contained within a row |
| IDataObject.getValue() | Gets a cell value on Page One, Page Two, or Page Three |
Before working with a cell's value, you must select the cell. Agile PLM cells are instances of attributes. To specify the attribute for a cell, specify either the attribute's ID constant, it's fully qualified name (such as "Title Block.Description"), or an IAttribute object. For more information about referencing attributes, refer to "Referencing Attributes" in SDK Developer Guide - Developing PLM Extensions.
|
Note: You can use ICell getAPIName() to access Data Cell attribute values. For information to use this field, see Chapter 8, "Accessing PLM Metadata with APIName Field." |
The following example shows how to reference a cell by attribute ID constant.
Example 5-3 Specifying a cell by ID
Object v;try { v = item.getValue(attrID);} catch (APIException ex) { System.out.println(ex);}
The following example shows how to reference a cell by the fully qualified attribute name.
String attrName = "Title Block.Number";
try {
v = item.getValue(attrName);
} catch (APIException ex) {
System.out.println(ex);
}
The method that you use to get a cell value depends on the current object in use by your program. Use the ICell.getValue() method if you have already retrieved an ICell object and want to retrieve a value.
Example 5-5 Getting a value using ICell.getValue()
private static Object getCellVal(ICell cell) throws APIException {Object v; v = cell.getValue(); return v;}
Quite often, your program will first retrieve an object, such as an item, and then use the IDataObject.getValue(java.lang.Object cellId) method to retrieve values for it.
Example 5-6 Getting a value using IDataObject.getValue(Object cellID)
private static Object getDescVal(IItem item) throws APIException { Integer attrID =
ItemConstants.ATT_TITLE_BLOCK_NUMBER; Integer attrID =
ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION; Object v; v = item.getValue(attrID); return v;}
The object returned by the getValue() method is of the same data type as the Agile PLM attribute. For more information about data types, see "Data Types."
|
Note: All cells in a table returned by a query contain String values regardless of the datatypes associated with those cells. For more information about query result tables, see "Working with Query Results." |
If you are iterating over rows in an Agile PLM table, you can use the IRow.getValues() method to retrieve a Map object containing all cell values for a particular row in the table. The returned Map object maps attribute ID keys to cell values.
In SDK, date is available as a Java Date object and does not format the date according to User Preferences. However, end users can convert it to their preferred format in GUI's User Preferences.
|
Important: End users must use the GMT date format for PPM dates. For more information, refer to the Agile PLM Product Portfolio Management User Guide. |
The following table lists Agile API methods for setting values for cells.
| Method | Description |
|---|---|
| ICell.setValue() | Sets a cell value |
| IRow.setValue() | Sets a cell value contained within a row |
| IRow.setValues() | Sets multiple cell values contained within a row |
| IDataObject.setValue() | Sets a cell value on Page One, Page Two, or Page Three |
| IDataObject.setValues() | Sets multiple cell values on Page One, Page Two, or Page Three |
The method you use to set a value depends on the current object in use by your program.
Use the ICell.setValue() method if you've already retrieved an ICell object and want to set its value.
Example 5-7 Setting a value using ICell.setValue()
private static void setDesc(ICell cell, String text) throws APIException { cell.setValue(text);}
If your program has already retrieved an object, such as a part, you can use the IDataObject.setValue() method to set its values.
Example 5-8 Setting a value using IDataObject.setValue()
private void setDesc(IItem item, String text) throws APIException { Integer attrID =
ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION; item.setValue(attrID, text);}
If you are iterating over rows in an Agile PLM table, you can use the IRow.setValues() method to set the cell values for an entire row. You can also use the IDataObject.setValues() method to set multiple cell values on Page One, Page Two, or Page Three of an object. The Map parameter you specify with setValues() maps attributes to cell values.
Example 5-9 Setting multiple values in a row using IRow.setValues()
private void setBOMRow(IRow row) throws APIException {
Map map = new HashMap(); map.put(ItemConstants.ATT_BOM_ITEM_NUMBER, "23-0753"); map.put(ItemConstants.ATT_BOM_QTY, "1"); map.put(ItemConstants.ATT_BOM_FIND_NUM, "0"); row.setValues(map);
}
When you set an Agile PLM value, you must know the cell's data type. If you try to set a cell's value using an object of the wrong data type, the method fails. You may need to cast the object to another class before using it to set a value.
|
Note: If you do not explicitly demarcate transactional boundaries in your code, every setValues() operation your program performs is treated as a separate transaction. |
If someone else is modifying an object, it is temporarily locked by that user. If you try to set the value for a cell when another user has the object locked, your program will throw an exception. Therefore, whenever your program sets values of cells, make sure you catch the following Agile exceptions related to locked objects:
ExceptionConstants.APDM_ACQUIRE_DBLOCK_FAILED
ExceptionConstants.APDM_RELEASE_DBLOCK_FAILED
ExceptionConstants.APDM_OBJVERSION_MISMATCH
You should also catch exception 813, which is related to locked objects.
The typical exception message that Agile PLM returns for a locked object is "Someone is working on this object. Please try again later."
For more information on handling exceptions, see Chapter 18, "Handling Exceptions."
There are two different datatypes for list cells. One for SingleList and one for MultiList cells. When you get the value for a SingleList or MultiList cell, the object returned is an IAgileList object. For that reason, list cells are slightly more complicated to work with than other cells. The IAgileList interface provides methods for getting and setting the current list selection. This section provides examples showing how to get and set values for different types of Agile PLM lists, including cascading lists.When you use ICell.getAvailableValues() to get the available values for a list cell, the returned IAgileList object may include obsolete list values. Your program should not permit users to set the value for a list cell to an obsolete value. For information on how to check whether a list value is obsolete, see "Making List Values Obsolete."When a list contains String values, the values are case-sensitive. This means that whenever you set the value for a list cell you must ensure that the value is the right case.
A SingleList cell allows you select one value from the list. When you get the value for a SingleList cell, the object returned is an IAgileList. From that IAgileList object, you can determine what the currently selected value is. The following example shows how to get and set values for the Title Block.Part Category cell for an item.
Example 5-10 Getting and setting the value for a SingleList cell
private static String getPartCatValue(IItem item) throws APIException {// Get the Part Category cell ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PART_CATEGORY);
// Get the current IAgileList object for Part Category IAgileList cl = (IAgileList)cell.getValue(
// Get the current value from the list String value = null; IAgileList[] selected = cl.getSelection(); if (selected != null && selected.length > 0) { value = (selected[0].getValue()).toString(); } return value; }
private static void setPartCatValue(IItem item) throws APIException {// Get the Part Category cell ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PART_CATEGORY);
// Get available list values for Part Category IAgileList values = cell.getAvailableValues();
// Set the value to Electrical values.setSelection(new Object[] { "Electrical" }); cell.setValue(values);}
A MultiList cell behaves very similar to a SingleList cell except that it allows you to select multiple values. A MultiList cell cannot be a cascading list. The following example shows how to get and set values for a MultiList cell, Title Block.Product Lines for an item.
Example 5-11 Getting and setting the value for a MultiList cell
private static String getProdLinesValue(IItem item) throws APIException {String prodLines;
// Get the Product Lines cell ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PRODUCT_LINES);
// Get the current IAgileList object for Product Lines IAgileList list = (IAgileList)cell.getValue();
// Convert the current value from the list to a string prodLines = list.toString(); return prodLines;}
private static void setProdLinesValue(IItem item) throws APIException {
// Get the Product Lines cell ICell cell = item.getCell(ItemConstants.ATT_TITLE_BLOCK_PRODUCT_LINES);
// Get available list values for Product Lines IAgileList values = cell.getAvailableValues();
// Set the Product Lines values values.setSelection(new Object[] {"Saturn","Titan","Neptune"}); cell.setValue(values);}}
You can reconfigure a SingleList cell to a cascading list. A cascading list presents a list in multiple hierarchical levels, enabling you to drill down to a specific value in the list hierarchy. For more information about cascading lists, see "Cascading Lists."When you get the value for a cascading list cell, a vertical bar (also called a piping character) separates each level in the cascading list. To select the value for a cascading list, use the IAgileList.setSelection() method. You can specify either an array of IAgileList leaf nodes or a String array containing one string delimited by vertical bars. After you select the value, save it using one of the setValue() methods.The following example shows how to get and set the value for a cascading list.
Example 5-12
private String getCascadeValue(IItem item) throws APIException {
String value = null;// Get the Page Two.List01 value IAgileList clist =
(IAgileList)item.getValue(ItemConstants.ATT_PAGE_TWO_LIST01);
// Convert the current value from the list to a string value = clist.toString(); return value;}private void setCascadeValue(IItem item) throws APIException { String value = null;
// Get the Page Two List01 cell ICell cell = item.getCell(ItemConstants.ATT_PAGE_TWO_LIST01);
// Get available list values for Page Two List01 IAgileList values = cell.getAvailableValues();
// Set the value to "North America|United States|San Jose" values.setSelection(new Object[]
{"North America|United States|San Jose"}); cell.setValue(values);}
Although the previous example shows one way to set the value for a cascading list, there is another longer form you that can use which illustrates the tree structure of the list. Instead of specifying a single String to represent a cascading list value, you can set the selection for each level in the list. The following example selects a value for a cascading list with three levels: continent, country, and city.
Example 5-13 Setting the value for a cascading list (long form)
private void setCascadeValue(IItem item) throws APIException{// Get the Page Two List01 cell ICell cell = item.getCell(CommonConstants.ATT_PAGE_TWO_LIST01);
// Get available list values for Page Two List01 IAgileList values = cell.getAvailableValues();
// Set the continent to "North America" IAgileList continent = (IAgileList)values.getChildNode("North America");
// Set the country to "United States" IAgileList country = (IAgileList)continent.getChildNode("United States");
// Set the city to "San JOse."
IAgileList city = (IAgileList)country.getChildNode("San Jose"); values.setSelection(new Object[]{city});
// Set the cell value cell.setValue(values);}
You can control how to use reference designator cells with Agile 9 SDK. You can make reference designator cells render collapsed or expanded depending on your system setting. The IReferenceDesignatorCell interface contains three public APIs that allow the end user to retrieve reference designator information in three formats:
Collapsed - for example A1-A3; use getCollapsedValue()
Expanded - A1, A2, A3; use getExpandedValue()
Array of individual reference designators-[A1, A2, A3]; use getReferenceDesignators[]
The following table lists Agile API methods for retrieving reference designator values for cells.
| Method | Description |
|---|---|
| IReferenceDesignatorCell.
getCollapsedValue() |
Gets a collapsed representation of the reference designators. For example, "A1,A2,A3" would be represented as "A1-A3". Note that the range separator, ("-") is defined as part of the system preferences. |
| IReferenceDesignatorCell.
.getExpandedValue() |
Gets an expanded value of a reference designator. For example, for "A1-A3" the string, "A1, A2, A3" would be returned. |
| IReferenceDesignatorCell.
getReferenceDesignators() |
Gets the individual reference designators as an array of strings. For example, for "A1-A3" an array of these three strings, ["A1", "A2", "A3"] would be returned. |
|
Note: In previous releases of Agile SDK, the value of a reference designator was a comma-delimited list of reference designators. Because the functionality of cell.getValue() for a reference designator will depend on the system setting controlling reference designator presentation, the SDK user should not use cell.getValue() or row.getValue(). We recommend that you get the cell and cast it into an IReferenceDesignatorCell; then call the method that corresponds to your desired data structure for processing or displaying reference designator information |
|
 Copyright © 2010, 2014, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|