| Agile Product Lifecycle Management Web Services Guide Release 9.3.5 E61173-02 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management Web Services Guide Release 9.3.5 E61173-02 |
|
Previous |
Next |
Before building a JAX-WS Web Services Client, verify if the following are in place:
Ensure that the Weblogic web service client jars are present in classpath:
com.oracle.webservices.fmw.client_12.1.3
com.oracle.webservices.wls.jaxws-wlswss-client.jar
Ant libraries are present.
The Ant build file contains the following:
<path id="build.classpath">
<fileset dir="${wlslib.dir}">
<include name="**/ com.oracle.webservices.wls.jaxws-wlswss-client.jar" />
</fileset>
</path>
<taskdef name="clientgen" classname="weblogic.wsee.tools.anttasks.ClientGenTask" classpathref=" build.classpath"/>
<target name="wsdl2java-Generate-Client">
<echo message="Generating all the client side stubs"/>
<clientgen wsdl="http://<host>:<port>/core/services/<serviceName>?wsdl" destDir="./src" type="JAXWS" fork="true"/>
</target>
Replace the <serviceName> with the name of the Web Service. For example: BusinessObject, Collaboration and so on.
Development platforms vary in their SOAP implementations. Implementation differences in certain development platforms may prevent access to some or all of the features in the API. If you are using Visual Studio for .NET development, it is recommended that you use Visual Studio 2003 or higher.
| Agile PLM Application | Release 9.3.5 |
|---|---|
| Default Web Services Engine | JAX-WS |
| Java 2 Platform Standard Edition Development Kit | 7.0 and 8.0 |
|
Note: Agile API programs connect to the Agile Application Server using secure and non-secure means. Consequently, it is recommended that you run the Agile API programs only from within the corporate firewall. Web service Clients, however, can connect to the server through the corporate firewall using standard HTTP(S) technology. |
The Agile PLM Web Services are implemented in compliance with the following standards:
| Standard | Location |
| Simple Object Access Protocol (SOAP) 1.1/1.2 | http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ |
| Web Service Description Language (WSDL) 1.2 | http://www.w3.org/TR/2001/NOTE-wsdl-20010315 |
| WS-I Basic Profile 1.1 | http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html |
| XML Schema 1.1 | http://www.w3.org/XML/Schema |
All application server vendors, such as Oracle and IBM, have built-in web service infrastructure solutions that are integrated with their application servers. For non-web services integrated applications, there are standard products which provides JAX-WS web service infrastructure that can be integrated with different application servers.
The stub acts as a gateway for client side objects and all outgoing requests to server side objects that are routed through it. The stub wraps client object functionality and by adding the network logic, ensures the reliable communication channel between client and server. The stub can be written up manually or generated automatically depending on the chosen communication protocol.
For Agile web services to function successfully, you must first create Agile PLM Server Stubs, and initialize the client side stubs.
To generate stubs, execute the Ant target wsdl2java-Generate-Client. All the stubs are created in src folder.
In the following sample, the generated stubs are being initialized for Business Object Web Services client. You may also adapt it for other web services.
String SERVER_URL = "http://<host>:<port>/core/services/BusinessObject"; String USERNAME = "admin"; String PASSWORD = "agile"; BusinessObjectService locator = new BusinessObjectService(new java.net.URL(SERVER_URL)); BusinessObjectPortType businessObjectStub = (BusinessObjectPortType)locator.getBusinessObject(); Map<String, Object> reqContext = ((javax.xml.ws.BindingProvider)businessObjectStub).getRequestContext(); reqContext.put(BindingProvider.USERNAME_PROPERTY, USERNAME); reqContext.put(BindingProvider.PASSWORD_PROPERTY, PASSWORD);
A new Java API called Java Architecture for XML Binding (JAXB) can make it easier to access XML content from applications, written in the Java programming language. JAXB allows Java developers to map Java classes to XML representations. It provides two main features: Marshalling and Unmarshalling
Marshalling - Allows you to convert Java object into XML Element representation.
// Sample method to marshal a AgileListEntryType list Object into XML
// Element object
public static Element marshal(Element element, AgileListEntryType agileListEntryType) {
JAXBContext jc;
try {
jc = JAXBContext.newInstance(AgileListEntryType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<AgileListEntryType> jaxbEl = new JAXBElement<AgileListEntryType>(new QName("",element.getNodeName()), AgileListEntryType.class, agileListEntryType);
marshaller.marshal(jaxbEl, element);
element = (Element) element.getFirstChild();
} catch (JAXBException e) {e.printStackTrace();} element.setAttribute("xmlns:xsi", "http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "AgileListEntryType");
return element;
}
Unmarshalling - Allows you to convert XML Element content into Java object.
// Sample method to unmarshall a XML Element object into an
// AgileListEntryType object
public static Object unmarshal(Element element) {
try {
JAXBContext jc = JAXBContext.newInstance(AgileListEntryType.class);
Unmarshaller unmarshaller = jc.createUnmarshaller();
Object obj = unmarshaller.unmarshal(element);
JAXBElement<?> jaxbEle = (JAXBElement<?>) obj;
return jaxbEle.getValue();
}catch (Exception e) {
e.printStackTrace();
return null;
}
}
For more details on how to use Archtecture for XML binding, see http://docs.oracle.com/middleware/1213/wls/WSGET/jax-ws-datatypes.htm#WSGET181
An Element is a part of a Request that specifies attributes of Agile Objects, which can use Agile API Names.
Most Elements are String Type, while some can be Unit of Measure Type or AgileListEntryType.
An Element can be assigned any Tag Name. When API name is used as Tag Name, you need not pass the 'attributeId'.
// Sample method to create a XML element with specified tag name
public static Element createMessageElement(String tagName) {
Document document = null;
try {
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder docBuilder = dbf.newDocumentBuilder();
document = docBuilder.newDocument();
} catch (ParserConfigurationException e) {
return null;
}
return document.createElement(tagName);
}
// create a XML element and set the text value.
Element element = createMessageElement("description");
element.setTextContent("Updated value of Doc Description");
When an API name is not used as Tag Name, the attributeId has to be explicitly passed as an XML attribute having the name 'attributeId'
Element element = createMessageElement("Message_Desc");
element.setAttribute("attributeId", ItemConstants.ATT_TITLE_BLOCK_DESCRIPTION.toString());
element.setTextContent("Updated value of Doc Description");
To obtain API names, open the desired Class in Agile Java Client. All the API names are found either in the General Information page or under the General Information tab.
The Element Types listed below require special handling.
The attributes of an Agile object that require 'Unit of Measure' as an input type are updated with the UOM values. These values are denoted by the Unit of Measure object. The corresponding object is AgileUnitOfMeasureType.
To update the attributes, you must send the data as an instance of AgileUnitOfMeasureType. In addition, you must pass the corresponding Namespace URI as an attribute. The format is:
element.setAttribute("xmlns:xsi", NAMESPACEURI);
element.setAttribute("xsi:type", CLASSNAME);
You are required to send correct values for NAMESPACEURI and CLASSNAME. For example:
COMMONNAMESPACEURI = "http://xmlns.oracle.com/AgileObjects/Core/Common/V1"
CLASSNAME = "AgileUnitOfMeasureType"
You can define your own namespaceUri or use COMMONNAMESPACEURI.
Example: Element for a UOM
AgileUnitOfMeasureType uom = new AgileUnitOfMeasureType(); uom.setUnitName("Kilogram");
uom.setUnitValue(1000.0);
Element element = createMessageElement("mass");
JAXBContext jc = JAXBContext.newInstance(AgileUnitOfMeasureType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<AgileUnitOfMeasureType> jaxbEl = new JAXBElement<AgileUnitOfMeasureType>(new QName("",element.getNodeName()),
AgileUnitOfMeasureType.class, uom);
marshaller.marshal(jaxbEl, element);
element = (Element) element.getFirstChild();
element.setAttribute("xmlns:xsi","http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "AgileUnitOfMeasureType");
The corresponding object is AgileListEntryType. You are required to pass the namespace attribute.
Example: Element for a Multilist
AgileListEntryType multilist01 = new AgileListEntryType(); SelectionType[] multiSelect = new SelectionType[3]; multiSelect[0] = new SelectionType(); multiSelect[0].setValue("Canceled");
multiSelect[1] = new SelectionType(); multiSelect[1].setValue("Complete"); multiSelect[2] = new SelectionType(); multiSelect[2].setValue("Accepted");
multilist01.getSelection().add(multiSelect[0]);
multilist01.getSelection().add(multiSelect[1]);
multilist01.getSelection().add(multiSelect[2]);
Element element = createMessageElement("multilist01");
JAXBContext jc = JAXBContext.newInstance(AgileListEntryType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<AgileListEntryType> jaxbEl = new JAXBElement<AgileListEntryType>(new QName("",element.getNodeName()),
AgileListEntryType.class, multilist01);
marshaller.marshal(jaxbEl, element);
element = (Element) element.getFirstChild();
element.setAttribute("xmlns:xsi","http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "AgileListEntryType");
Example: Element for a List
AgileListEntryType list01 = new AgileListEntryType(); SelectionType[] selection = new SelectionType[1]; selection[0] = new SelectionType(); selection[0].setValue("Alternate");
list01.getSelection().add(selection[0]);
Element element = createMessageElement("list01");
JAXBContext jc = JAXBContext.newInstance(AgileListEntryType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<AgileListEntryType> jaxbEl = new JAXBElement<AgileListEntryType>(new QName("",element.getNodeName()),
AgileListEntryType.class, list01);
marshaller.marshal(jaxbEl, element);
element = (Element) element.getFirstChild();
element.setAttribute("xmlns:xsi","http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "AgileListEntryType");
In certain cases, Agile SDK expects a list of IDataObject to be passed. For such cases, Agile Web Services use AgileObjectListEntryType.
AgileObjectListEntryType multilist01 = new AgileObjectListEntryType(); ObjectReferentIdType[] obj = new ObjectReferentIdType[1];
obj[0] = new ObjectReferentIdType(); obj[0].setClassIdentifier("8750"); obj[0].setObjectIdentifier("SAP0265");
multilist01.getSelection().add(obj);
Element element = createMessageElement("supplier");
JAXBContext jc = JAXBContext.newInstance(AgileObjectListEntryType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<AgileObjectListEntryType> jaxbEl = new JAXBElement<AgileObjectListEntryType>(new QName("",element.getNodeName()),
AgileObjectListEntryType.class, multilist01);
marshaller.marshal(jaxbEl, element);
element = (Element) element.Element url = createMessageElement("Message_URL");
url.setAttribute("attributeId", ReferenceObjectConstants.ATT_GENERAL_INFO_URL.toString());
url.setTextContent("New URL");
rows.getAny().add(url);
agileUpdateObjectRequest[0].setData(rows); updateObjectRequestType.setRequests(agileUpdateObjectRequest); UpdateObjectResponseType updateObjectResponseType = businessObjectStub.updateObject(updateObjectRequestType);getFirstChild();
element.setAttribute("xmlns:xsi","http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "AgileObjectListEntryType");
The corresponding object is AgileMoneyType. You are required to pass the namespace attribute.
Example: Element for Money
AgileMoneyType money = new AgileMoneyType(); money.setAmount(997777.9); money.setCurrency("USD");
Element element = createMessageElement("money01");
JAXBContext jc = JAXBContext.newInstance(AgileMoneyType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<AgileMoneyType> jaxbEl = new JAXBElement<AgileMoneyType>(new QName("",element.getNodeName()),
AgileMoneyType.class, money);
marshaller.marshal(jaxbEl, element);
element = (Element) element.getFirstChild();
element.setAttribute("xmlns:xsi","http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "AgileMoneyType");
Java provides an object either as Date or as Calendar objects. You are required to pass the namespace attribute. Date is a special case. Even though it is an XSD type, you must pass URI for Date.
Example: Element for Date
Element element = createMessageElement("date01"); JAXBContext jc = JAXBContext.newInstance(Date.class);Marshaller marshaller = jc.createMarshaller();JAXBElement<Date> jaxbEl = new JAXBElement<Date>(new QName("",element.getNodeName()), Date.class, new Date();marshaller.marshal(jaxbEl, element);element = (Element) element.getFirstChild();element.setAttribute("attributeId", ItemConstants.ATT_PAGE_TWO_DATE01.toString());element.setAttribute("xmlns:xsi","http://www.w3.org/2001/XMLSchema");element.setAttribute("xsi:type", "date");
The corresponding object is ObjectReferentIdType. You are required to pass the namespace attribute.
Example: Element for a User
ObjectReferentIdType user = new ObjectReferentIdType(); user.setObjectIdentifier("EMS1"); user.setClassIdentifier("supplier");
Element element = createMessageElement("supplier");
JAXBContext jc = JAXBContext.newInstance(ObjectReferentIdType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<ObjectReferentIdType> jaxbEl = new JAXBElement<ObjectReferentIdType>(new QName("",element.getNodeName()),
ObjectReferentIdType.class, user);
marshaller.marshal(jaxbEl, element);
element = (Element) element.getFirstChild();
element.setAttribute("xmlns:xsi","http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "ObjectReferentIdType");
Example: Element for a Customer
ObjectReferentIdType customer = new ObjectReferentIdType(); customer.setObjectIdentifier("DEMO CUSTOMER 1"); customer.setClassIdentifier("customer");
Element element = createMessageElement("customer");
JAXBContext jc = JAXBContext.newInstance(ObjectReferentIdType.class);
Marshaller marshaller = jc.createMarshaller();
JAXBElement<ObjectReferentIdType> jaxbEl = new JAXBElement<ObjectReferentIdType>(new QName("",element.getNodeName()),
ObjectReferentIdType.class, customer);
marshaller.marshal(jaxbEl, element);
element = (Element) element.getFirstChild();
element.setAttribute("xmlns:xsi","http://xmlns.oracle.com/AgileObjects/Core/Common/V1");
element.setAttribute("xsi:type", "ObjectReferentIdType");
|
Note: You can pass values like String and Numbers as they are. However, you cannot pass numbers as strings. |
The following attributes do not have an API name. You are required to use the Attribute IDs, listed below. These values have been picked from Agile SDK Constants. For more information, refer to Agile PLM SDK Developer Guide.
| TABLE_REDLINEBOM | new Integer(-803); |
| TABLE_REDLINEMANUFACTURERS | new Integer(-1491); |
| TABLE_REDLINETITLEBLOCK | new Integer(-801); |
| TABLE_REDLINEPAGETWO | new Integer(-810); |
| TABLE_REDLINEPAGETHREE | new Integer(-1501); |
| FLAG_IS_REDLINE_MODIFIED | new Integer(-101); |
| FLAG_IS_REDLINE_REMOVED | new Integer(-102); |
| FLAG_IS_REDLINE_ADDED | new Integer(-103); |
A majority of operations carried out within the system comprises of a single request and response.
To initiate an action, the client application issues a request. The request contains the necessary information to determine which operation is being carried out. The data and format depends on the type of operation being carried out.
The response contains the specific data that was requested. Based on the request that is issued, the system retrieves a response with relevant information.
The response obtained from every Web service call contains a response statusCode, which indicates the success or failure of a Web service operation. These Status Codes are of four types:
SUCCESS- indicates that all Web services in the batch were executed successfully and that all operations worked as intended.
FAILURE - indicates that all Web services in the batch failed during execution, indicating the intended operations were not performed.
WARNING - indicates that though Web services in the batch were successfully executed, certain warnings were also encountered during the execution. These warnings must be analyzed by the client to verify that all operations worked as intended.
PARTIAL_SUCCESS - indicates a partial success in the execution of batch Web services - when one or more but not all batch requests have failed. The response status code will display PARTIAL_SUCCESS even if a single Web service among a batch of Web services fails.
When an operation is not successful, the system will throw an Exception or a Warning.
In case of FAILURE, an exception is issued, while a warning may or may not be issued.
In case of WARNING, only a warning is issued.
When the status is WARNING, the outcome of the operation is unknown. You are manually required to check whether the operation was successful or not.
The response header for Web Services calls consists of a list of exceptions and warnings populated as AgileExceptionListType and AgileWarningListType objects. The application client must check for exceptions and warnings always to ensure that the code has performed all operations as intended.
The exception and warning lists contain a reference element 'id' which may be used to identify the corresponding requested in the batch that was the source of the exception(s) or warning(s).
Refer to the schema for dealing with response objects for a particular Web Service.
Example: Getting Exceptions and Warnings
if( !approveRObjectResponseType.getStatusCode().toString().equals( ResponseStatusCode.SUCCESS.getValue() ) ){ AgileExceptionListType[] agileExceptionListType = approveRObjectResponseType.getExceptions();
if(agileExceptionListType!=null)
for(int i=0; i<agileExceptionListType.length; i++){
AgileExceptionType exceptions[] = agileExceptionListType[i].getException();
for(int j=0; j<exceptions.length; j++)
System.out.println("Exception Id:" + exceptions[j].getExceptionId() + "\nMessage: " +
exceptions[j].getMessage() );
}
AgileWarningListType agileWarningListType[] = approveRObjectResponseType.getWarnings();
if(agileWarningListType!=null)
for(int i=0; i<agileWarningListType.length; i++){
AgileWarningType warnings[] = agileWarningListType[i].getWarning(); for(int j=0; j<warnings.length; j++)
System.out.println("Warning Id: " + warnings[j].getWarningId() + "\nMessage: " +
warnings[j].getMessage() );
}
}
|
Note: By default, all warnings are enabled. |
You can work with warnings in the following ways:
Use setWarningResolution to selectively Enable or Disable a select set of warnings.
AgileWarningResolutionType warningRes[] = new AgileWarningResolutionType[1]; warningRes[0] = new AgileWarningResolutionType();warningRes[0].setId(182); warningRes[0].setResolution(AgileWarningResolutionConstantsType.DISABLE); approveRObjectRequestType.setWarningResolution(warningRes);
Use diasableAllWarnings function to disable ALL the warnings
approveRObjectRequestType.setDisableAllWarnings();
Enable a select set of warnings and disable the rest with a combination of diasableAllWarnings and setWarningResolution.
approveRObjectRequestType.setDisableAllWarnings(); AgileWarningResolutionType warningRes[] = new AgileWarningResolutionType[1]; warningRes[0] = new AgileWarningResolutionType();warningRes[0].setId(182); warningRes[0].setResolution(AgileWarningResolutionConstantsType.ENABLE); approveRObjectRequestType.setWarningResolution(warningRes);
