The eBay SDK for Java based on Apache Axis 1.1 will be deprecated in the future. This document is intended for users who have previously installed that version and are migrating to the JAX-WS eBay SDK for Java.
Please note the following important information:
Please note the following important information about migrating to this SDK:
Please note the following important SDK code changes:
For detailed information about these changes, including code snippets, please see Differences Between eBay SDKs when Migrating from Axis 1.1 to JAX-WS below.
This section describes how to install the JAX-WS eBay SDK for Java if you have already installed the previous Axis 1.1 eBay SDK for Java.
The complete migration should always be done in a test environment and should be fully tested before use in production.
Update and run the ..\SDKInstallDir\setenv.bat file as described below if any of the following apply:
Building the JAX-WS eBay SDK is necessary only for advanced users who have added a customization to the JAX-WS eBay SDK's source code or need to synchronize the source code with a new version of the eBay Web Services Definition Language (WSDL).
The majority of users can skip to the second step in Migrating the eBay SDK from Axis 1.1 to JAX-WS after installing the JAX-WS eBay SDK as described in Installation Instructions, if no upgrades to Apache ANT or the JDK were completed.
Modify the ..\SDKInstallDir\setenv.bat file as follows:
The JAX-WS eBay SDK for Java offers various improvements over the Axis 1.1 eBay SDK for Java. These include improvements in performance, standardized solutions, parsing, stability and flexibility at the transport level, among others.
In the Axis 1.1 eBay SDK for Java, source code customization was made to the Axis framework in an effort to increase performance metrics, add improved exception handling and implement other enhancements. This customization ultimately proved difficult to maintain across SDK versions. Additionally, the feedback from many of our developers indicated that this SDK was too dependent on the customized Axis framework, thus not being as configurable as desired.
Thus, for the JAX-WS eBay SDK for Java, no source code customization has been made to the JAX-WS RI. In other words, the JAX-WS RI that is included in the JAX-WS release can be downloaded from the official JAX-WS RI website. The limited number of Java Architecture for XML Binding (JAXB) custom bindings can be found in the ..\SDKInstallDir\custom-binding.xml file, and these will be periodically updated between SDK versions. Because such customization is built using JAXB technology and decoupled from the JAX-WS RI source code, it is non-intrusive and straightforward to maintain.
The changes described in this section apply to classes in the com.ebay.soap.eBLBaseComponents package. Code changes to other packages within the JAX-WS eBay SDK arise from changes to com.ebay.soap.eBLBaseComponents, as these other packages use classes from com.ebay.soap.eBLBaseComponents. As an example, changes to the com.ebay.sdk package are based on changes to classes in com.ebay.soap.eBLBaseComponents, and are not documented here.
The following classes have been removed from com.ebay.soap.eBLBaseComponents package and have been replaced with java.lang.String:
Axis 1.1 Class |
JAX-WS Equivalent |
---|---|
BestOfferIDType.java | java.lang.String |
BidderIDType.java | java.lang.String |
DisputeIDType.java | java.lang.String |
ItemIDType.java | java.lang.String |
MyMessagesAlertIDType.java | java.lang.String |
MyMessagesMessageIDType.java | java.lang.String |
OrderIDType.java | java.lang.String |
RecipientRelationCodeType.java | java.lang.String |
SKUType.java | java.lang.String |
UserIDType.java | java.lang.String |
UUIDType.java | java.lang.String |
Note that BidderIDType.java was an orphaned data type, as it was not referenced by other data types in our WSDL. Code changes will only apply to the other data type classes listed above.
The java.lang.String class replaces these wrapper classes in the JAX-WS eBay SDK, simpifying the code by eliminating the need to instantiate or use a separate object when needing access to these simple data values. Wherever a method expected an instance of any one of these classes as a parameter, a java.lang.String must be passed instead. Furthermore, a method that returned an instance of one of these classes will return a java.lang.String.
The following code example illustrates the use of an instance of the ItemIDType class in the Axis 1.1 eBay SDK:
EndItemCall call = new EndItemCall(this.apiContext); //strItemID is a java.util.String private field containing the itemID if( this.strItemID.length() == 0 ) throw new SdkException("Please enter item ID."); //we must first create an ItemIDType object to populate our call ItemIDType item = new ItemIDType(this.strItemID); call.setItemID(item);
Using java.lang.String in the JAX-WS eBay SDK is simpler:
EndItemCall call = new EndItemCall(this.apiContext); //strItemID is a java.util.String private field containing the itemID if( this.strItemID.length() == 0 ) throw new SdkException("Please enter item ID."); //no need to instantiate a ItemIDType object here call.setItemID(this.strItemID);
Also, in the JAX-WS eBay SDK, a java.lang.String must be used to specify a URI/URL whenever an org.apache.axis.types.URI object was expected in the Axis 1.1 eBay SDK. Again, this eliminates the need for the extraneous wrapper object. However, the URI must be valid or the server will return an error. You can optionally use java.net.URI to validate the URL by instantiating a java.net.URI object and then using the toString() method, as illustrated below. Note that a URISyntaxException, which is a checked exception, will be thrown if the java.net.URI does not conform with the RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax standard.
The code snippet below illustrates the typical use of an org.apache.axis.types.URI object in the Axis 1.1 eBay SDK:
PictureDetailsType picDetails = new PictureDetailsType(); ... org.apache.axis.types.URI myURI = new org.apache.axis.types.URI("https://www.yourpicsource.com/index.php?itemID=1234"); picDetails.setGalleryURL(myURL);
Here's the same code snippet in the JAX-WS eBay SDK:
PictureDetailsType picDetails = new PictureDetailsType(); ... picDetails.setGalleryURL("https://www.yourpicsource.com/index.php?itemID=1234");
If you would prefer to dynamically validate your URL endpoint, use java.net.URI as follows.
Keep in mind that URISyntaxException is a checked exception, so you must either surround the code below
within an exception-handling try-catch
block or declare throws URISyntaxException
in the method signature.
An example of the try-catch
block is illustrated:
try { java.net.URI validURL = new java.net.URI("https://www.yourpicsource.com/index.php?itemID=1234"); } catch(java.net.URISyntaxException e) { throw new java.lang.IllegalArgumentException("Please specify a valid URL."); } picDetails.setGalleryURL(validURL.toString());
As with URI/URLs, a java.lang.String will also replace an org.apache.axis.types.Token class in the JAX-WS eBay SDK. For an example of this replacement, please refer to the next section.
The following changes apply to enum constant names:
The following lines of code illustrate the names of enum constants when using the Axis 1.1 eBay SDK:
BuyerPaymentMethodCodeType[] paymentMethods = new BuyerPaymentMethodCodeType[] {BuyerPaymentMethodCodeType.Other, BuyerPaymentMethodCodeType.PayPal};
Here's the same line using the JAX-WS eBay SDK:
BuyerPaymentMethodCodeType[] paymentMethods = new BuyerPaymentMethodCodeType[] {BuyerPaymentMethodCodeType.OTHER, BuyerPaymentMethodCodeType.PAY_PAL};
The described changes apply to all enumeration classes. The naming convention used for enumeration classes in com.ebay.soap.eBLBaseComponents is usually: ClassNameCodeType.java.
The fromString() method is deprecated from all enumeration classes in the com.ebay.soap.eBLBaseComponents package in the JAX-WS eBay SDK, as the org.apache.axis.types.Token class is no longer available.
However, the fromValue() method, which accepts a java.lang.String as a parameter, can now be used to directly convert a String to an enum constant in the JAX-WS eBay SDK. Note that the fromValue() method from the Axis 1.1 eBay SDK previously accepted an org.apache.axis.types.Token class as a parameter.
Also, the value() method in an enumeration class in the JAX-WS eBay SDK will now return a java.lang.String instead of an org.apache.axis.types.Token.
Regarding implementation in the JAX-WS eBay SDK, classes representing enumerations are implemented as Java Enum classes. Their class definitions start with:
public enum EnumName {
Since these classes collectively have a nearly identical public interface, some methods previously available in Axis 1.1 enumeration classes are no longer defined in these Enum classes.
For example, enumeration classes in the Axis 1.1 eBay SDK:
Although enumerations defined by Java Enum classes in the JAX-WS eBay SDK implement the java.io.Serializable interface for backwards compatibility, the methods listed above are no longer available.
The described changes apply to all enumeration classes. The naming convention used for enumeration classes in com.ebay.soap.eBLBaseComponents is usually: ClassNameCodeType.java.
Any public or private method with a signature that either accepts parameters or returns objects from packages within the org.apache.axis hierarchy will no longer be available in com.ebay.soap.eBLBaseComponents classes. In most cases, these methods are no longer needed due to the new JAX-WS/JAXB framework, or they might have been replaced by equivalent methods.
The following classes previously defined two constructors in their class definitions: a default (no-args) constructor and another constructor with a parameter like java.lang.String. In the JAX-WS eBay SDK, only a default (no-args) constructor is available for the following data classes:
Due to changes in stub generation, the JAX-WS eBay SDK will generate these com.ebay.soap.eBLBaseComponents classes with only a default constructor.
Whenever a class in com.ebay.soap.eBLBaseComponents defines a private java.lang.Boolean instance field, and if the public interface for the class includes a getter (accessor) method to retrieve this object from the instance, the getter method generated by the JAX-WS eBay SDK will always be named as follows: the word "is" prefixed to the name of the private instance field.
As an example, the com.ebay.soap.eBLBaseComponents class GetItemTransactionsRequestType.java defines the following private instance fields of type java.lang.Boolean:
IncludeFinalValueFee
IncludeContainingOrder
JAXB's wsimport will generate the following getter methods for these java.lang.Boolean fields:
isIncludeFinalValueFee()
isIncludeContainingOrder()
Also, wsimport creates setter (mutator) methods for these instance fields prefixing the customary word "set" to the name of the fields:
setIncludeFinalValueFee( Boolean value )
setIncludeContainingOrder( Boolean value )
Note that this naming convention, as well as many of the other code changes described here, are required by the JAXB specification, and not by eBay.
When creating getters and setters for private instance fields of data types other than java.lang.Boolean, JAXB's wsimport creates methods that are identical to Axis 1.1's wsdl2java. That is, getters are prefixed with "get" and setters are prefixed with "set", as expected:
public double getCurrencyAmount()
public void setCurrencyAmount( double amt )
© 2005–2010 eBay Inc. All rights reserved.