| Agile Product Lifecycle Management Web Services Guide Release 9.3.6 E71166-01 |
|
 Previous |
This section describes helper methods and other aspects useful for developing the web services.
The Java sample codes covered in this book (based on the JAX-WS framework) and those available for download from Oracle Software Delivery Cloud, demonstrate various usage characteristics of Agile 936 Web Services.
|
Note: There are two types of samples available: security and non-security. When the security policy is enabled the non-security sample code does not work. |
Apart from outlining the basic cases for each Web Service, they also elaborate upon more specific cases that involve usage of options or mandatory message elements.
Download these Sample Codes in 'src' directory. They are categorized into different packages based on the type of Web Service, which are AdminMetaData, Attachment, Business, Collaboration, PC, Search and Table.
Batch files for building and running samples independent of a Java IDE are also provided.
A batch file build.bat located in the main directory JavaWeb Servicesamples is also provided. This batch file uses ant tasks to generate stubs for Agile Web Services and compiles the java sample files after generation of these stubs.
Along with build.bat, a custom.properties file which specifies the basic configuration properties, such as the Agile server URL, username, password, and also the URL of DFM is also provided. Unless you edit this property file is edited to reflect the values appropriate for your Agile environment, you cannot generate stubs or run the samples.
After ensuring appropriate modification of 'custom.properties', run the batch file 'build.bat'. Running the same through a command prompt helps in identifying error statements (if any) that are echoed onto the console. If the message 'BUILD SUCCESSFUL' displays on the console then the build process was completed without any errors. However, if the message 'BUILD FAILED' is observed on the console, your 'custom.properties' configuration may be incorrect and you must verify the same.
The stubs and the compiled samples are added to the folder build/built/*.jar as two jar files 'ws_samples.jar' and 'ws_stubs.jar' which are used later while running the sample.
After building the stubs and compiling the sample files, any sample file can be readily executed using the batch file run.bat and specifying the fully qualified class name as an argument.
Browse the source directory 'JAX-WSsamples/src' to find the package structure of the sample that you are looking for.
For example, to the run the sample 'CreateObjectAPIName' that creates an object using API names, the following command must be executed through command prompt:
run business.create.CreateObjectAPIName
Similarly, to run a sample from another sample package, say AddRowsSiteSpecific of the table Web Service, use the command:
run table.addrows.AddRowsSiteSpecific
If no argument is passed to run.bat, then all the available samples will be executed sequentially.
|
Note: While running samples using this ant task, the Agile server URL, username and password properties are retrieved from the same 'custom.properties' file that was used for building stubs. |
To run the sample files from a Java IDE, such as JDeveloper or Eclipse, create a new project or workspace in your IDE (as applicable to your IDE) and in your project properties modify / add project source paths to include the 'JavaWeb Servicesamples/src' directory where the sample source code is located.
You also need to update your project library or classpath information to include all the necessary jars of weblogic JAX-WS client and other Agile jar files which are used during sample development.
Ensure to add the jar files under the folders 'JAX-WS-Sample/build/wlslib' and 'JAX-WS-Sample/build/ant' to your library / classpath.
Any sample file can now be executed by browsing through the package structure, and running the desired sample.
The static variables relating to Agile server url, username and password in each java sample must be modified, if you choose to run the sample through an IDE.
Each java sample file contains header documentation at the class level explaining the functionality or usage scenario that the sample demonstrates. A set of static variables relating to server url, username, password and variables specific to that sample, like partNumber or folderName or nextStatus, are declared here.
If the sample is executed using the ant task (through run.bat), then the server configuration related static variables are overridden by the method checkArguments(String[] args(), which obtains arguments from the ant task and reinitializes server URL username, password and DFM URL variables.
If a sample is executed through a Java IDE, the server configuration variables must be modified manually to reflect the server settings of your Agile server.
With the exception of adminMetaData services, all samples provided here use the method prepareData() to prepare all the data prerequisites necessary to create a scenario using which, a particular Web Service may be demonstrated meaningfully.
For example, if the sample demonstrates usage of the operation loadTable to load a table from a particular version of an Agile object, prepareData() does the following:
Creates a part object
Adds a change, modifies the part
Provides a new version number
Releases the change.
After you prepare the data, the operation loadTable is used with the option 'version' to demonstrate the retrieval of a table from a particular version of an Agile object.
If you intend to use your own data or scenario to execute a Web Service sample, comment out the 'prepareData();' statement in the main method of that sample, edit the static variables at the top of the code and specify your own data.
All the operations performed in data preparation are also achieved using Agile PLM 934 Web Services. To gain a broader understanding of how Web Services are used in conjunction to orchestrate a larger task, examine the file DataPrepare.java in the package src/run/DataPrepare.java.
The sample files are documented with comments at each stage and evince several usage characteristics of these Web Services while illustrating how basic requests are formed and how the responses obtained are used.
The getRowID and getFileId are custom helper methods. These are not Agile Web Services operations.
Service
To obtain the rowId or fileId for a row on an Agile table.
Usage
Several table and attachment operations require the rowId or fileId as input for executing a Web Service. Load the table that contains the required row using the loadTable operation. It is then iterated through the results until the row is found.
To find a particular row in a table, use a keyword to search and identify the row. In this example, the filename is used as the key to identify a row.
Search all the rows available in the attachment table and compare all message elements with tag names 'filename' with the filename specified by the client, looking for a match. Once a match is found, the rowId information is derived from the row and returned.
Compare all 'filename' message elements, searching for a match with the filename specified by the user. If a match is found, return either the fileId or rowId based on the requirement.
|
Note: getValueFromSelection is a method written in this sample that handles all message elements of type AgileListEntryType. Since 'filename' is a message element of AgileListEntryType, the values are elicited by this method. |
Handle all AgileListEntryType message elements, cycle through the selection element, obtain the actual selection value, selection Id and add it to a HashMap. Here, selection value denotes the filename, while the selection Id denotes the fileId.
In Filefolders, the message element for filename is not an AgileListEntryType. The value may be obtained directly.
To get RowID or FileID:
Create the request object LoadTableRequestType for the loadTable operation.
For each request, specify the table to which the row belongs.
Tables in Agile Web Services are defined as RequestTableType objects. Specific tables are identified by specifying the class identifier and table identifier attributes.
The request objects are set and the Agile Stub makes the loadTable Web Service call. The status code obtained from the response object is printed to verify the success of the loadTable operation.
If the status code indicates 'SUCCESS', use the table results to find the required row. Once the row is found, its rowId or fileId is returned. If the status code indicates that the Web Service call was not successful, populate a list of exceptions.
Search for the required row by using the filename to look for a match and return the rowId or fileId.
Sample Code
getRowIdOrFileId
public static int getRowOrFileId(String filename, String clazz, String objectNumber, String tableId, String methodType){
try{
setupServerLogin_LoadTable();
LoadTableRequestType loadTableRequestType = new LoadTableRequestType();
RequestTableType table = new RequestTableType();
table = new RequestTableType();
table.setClassIdentifier(clazz);
table.setObjectNumber(objectNumber);
table.setTableIdentifier( tableId );
loadTableRequestType.getTableRequest().add(table);
LoadTableResponseType loadTableResponseType = agileStub_Table.loadTable(loadTableRequestType);
if( loadTableResponseType.getStatusCode().toString().equals( ResponseStatusCode.SUCCESS.value() ) ){
AgileTableType[] tables = loadTableResponseType.getTableContents().toArray(new AgileTableType[0]);
return getRowOrFileId(tables, "filename", filename, methodType);
}
else {
AgileExceptionListType[] agileExceptionListType = loadTableResponseType.getExceptions().toArray(new AgileExceptionListType[0]);
if(agileExceptionListType!=null)
for(int i=0; i<agileExceptionListType.length; i++){
AgileExceptionType exceptions[] = agileExceptionListType[i].getException().toArray(new AgileExceptionType[0]);
for(int j=0; j<exceptions.length; j++)
System.out.println(exceptions[j].getMessage() );
}
AgileWarningListType agileWarningListType[] = loadTableResponseType.getWarnings().toArray(new AgileWarningListType[0]);
if(agileWarningListType!=null)
for( int i=0; i<agileWarningListType.length; i++){
AgileWarningType warnings[] = agileWarningListType[i].getWarning().toArray(new AgileWarningType[0]);
for(int j=0; j<warnings.length; j++)
System.out.println("Warning Id: " + warnings[j].getWarningId() + "\nMessage: " + warnings[j].getMessage() );
}
}
} catch (Exception ex) {
ex.printStackTrace();
}
return -1;
}
public static int getRowOrFileId(AgileTableType[] tables, String keyTag, String keyValue, String methodType) throws Exception{
if(tables!=null)
for(int i=0; i<tables.length; i++){
AgileRowType[] rows = tables[i].getRow().toArray(new AgileRowType[0]);
if(rows!=null)
for(int j=0; j<rows.length; j++){
List<Element> messages = rows[j].getAny();
for(int m=0; m<messages.size(); m++){
Object element = messages.get(m);
String strName = "";
HashMap fileValues[] = null;
if (element instanceof Element) {
strName = ((Element)element).getNodeName();
if( strName.equalsIgnoreCase( keyTag ) )
fileValues = getValuesFromSelection((Element)element, keyTag);
}
else if (element instanceof JAXBElement) {
strName = ((JAXBElement<?>)element).getName().getLocalPart();
if( strName.equalsIgnoreCase( keyTag ) ) {
JAXBElement<?> jEle = (JAXBElement<?>)element;
AgileListEntryType lstEntry = (AgileListEntryType)jEle.getValue();
fileValues = getValuesFromSelection(lstEntry, keyTag);
}
}
if (fileValues != null) {
for(HashMap fileValue:fileValues)
if( fileValue.get( keyTag ).equals(keyValue) ){
if(methodType.equals("getRowId"))
return rows[j].getRowId();
else
if(methodType.equals("getFileId"))
return (Integer) fileValue.get("fileid");
}
}
}
}
}
return 0;
}
public static HashMap[] getValuesFromSelection(Element element, String keyTag) throws Exception{
HashMap fileValues[] = null;
String xsiType = element.getAttributeNS("http://www.w3.org/2001/XMLSchema-instance", "type");
if("common:AgileListEntryType".equals(xsiType)) {
AgileListEntryType list = (AgileListEntryType)WSUtil.unmarshalToAgileListEntryType(element) ;
SelectionType selection[] = list.getSelection().toArray(new SelectionType[0]);
fileValues = new HashMap [selection.length];
for(int i=0; i<selection.length; i++){
fileValues[i] = new HashMap();
fileValues[i].put( keyTag, selection[i].getValue() );
fileValues[i].put("fileid", selection[i].getId() );
}
}
else{
fileValues = new HashMap [1];
fileValues[0] = new HashMap();
fileValues[0].put( keyTag, element.getFirstChild().getNodeValue() );
fileValues[0].put("fileId", null );
}
return fileValues;
}
Issue #7639814: API names are not available for a huge set of lists.
Resolution: GetLists Admin service is supported only for Admin Lists found in JavaClient>Admin>Lists. Some class specific lists are not exposed in Admin Lists.
To get values for these Lists, use GetAttributes Admin service, which returns AttributeType. This has availableValues as AdminListType. Use these List values for updateObject or createObject.
Issue #8253064: Group sign-off option cannot be set from Web Services.
Resolution: Group sign-off is not supported in the current release.
Issue #9308516: undoRedline operation error message does not convey the wrong "option name" given.
Resolution: If you do not use option "redline_change", or if it is wrongly entered as "redline_chg", the correct revision of the item is not loaded. Only the latest released revision is loaded. In that revision of the item BOM table, the given row id is invalid and hence the invalid rowId exception is thrown. The behavior seems acceptable.
