CarrierLib shipcloud Example
Please read the following steps to use the CarrierLib Java library. This example demonstrates the usage of the shipcloud© functions included in the CarrierLib ZIP/TGZ archives.
![]() |
Please keep in mind that running this example may generate costs at shipcloud! To avoid that please sign up for a demo/test account on the shipcloud website. |
- Step 1: Download CarrierLib ZIP/TGZ
- Step 2: Running The shipcloud Example
- Step 3: The shipcloud Example Step By Step
Step 1: Download CarrierLib ZIP/TGZ
First of all please download the current CarrierLib ZIP/TGZ archive on your computer. Choose the archive which can be best extracted from your computer (e.g. ZIP for Windows, TGZ for UNIX, ...). The ZIP archive may be unzipped directly from Ant build scripts using the unzip task into a local directory of your choice. Of course you can extract the CarrierLib ZIP archive manually with WinZIP or other ZIP extraction tools.
The listing below shows the contents of the current CarrierLib archives (list shows relevant files/folders only, library versions may change for newer CarrierLib versions):
api/
api/index.html
example/
example/build-examples.xml
example/com/lf/carrierlib/test/shipcloud/ExampleShipcloudV1Production.java
example/com/lf/carrierlib/test/shipcloud/ExampleShipcloudV1Sandbox.java
extlib/
extlib/commons-logging-1.1.jar
extlib/jackson-annotations-2.2.3.jar
extlib/jackson-core-2.2.3.jar
extlib/jackson-databind-2.2.3.jar
extlib/vfs-2.0.jar
lib/
lib/carrierlib-1.6.1.jar
lib/carrierlib-eng_US-1.6.1.jar
lib/carrierlib-ger_DE-1.6.1.jar
license/
README.html
release_notes.html
The ZIP archive contains various files and resources for CarrierLib. The API (Javadoc) can be displayed by opening the index.html file with your favorite Internet browser. In the example folder you can find the precompiled shipcloud example code to be executed directly or using Apache Ant.
The extlib folder contains the additional libraries needed to run the CarrierLib properly. If you plan to use the shipcloud interface you will have to add the Commons libraries and Jackson to the classpath. The lib folder contains the CarrierLib libraries including some language packs (English and German at the moment). The English language pack is mandatory and must be included always along with the main CarrierLib JAR file. The other language packs are only needed if your application supports these languages.
In the license folder you can find the CarrierLib license as well as the licenses for the 3rd party JAR files residing in extlib. Please take a look at the README.html as a condensed overview of the package. The current release notes for the package can be found in the release_notes.html file.
![]() |
A compatible Java Runtime Environment (JRE) must be installed prior to the installation of Apache Ant. Most developers can use their normal development environment here. Some IDEs like Netbeans which include a compatible JRE and Ant installation may support the direct execution of Ant build scripts. |
Step 2: Running The shipcloud Example
The CarrierLib for shipcloud example can be easily executed using Apache Ant. If not already installed please download and install a recent Ant for your operating system. Then you should add the Ant installation folder with the Ant executables to your local classpath so that the ant command may be executed directly from the extracted ZIP/TGZ archive folder (see secion Download CarrierLib ZIP/TGZ).
Please open a command line (e.g. MS-DOS under Windows) and type the following commands:
cd [CarrierLib installation folder]\example
ant -file build-examples.xml run-shipcloud-v1-sandbox
![]() |
Anyway you will need to run the example in a graphical environment since the classes display dialogs to prompt the user for the parameters necessary for shipcloud. |
As figure 1 shows a dialog is being displayed then where you can specify the (evaluation) license for CarrierLib. If the license is not valid the example class exits with a message. If you specified a valid license the example proceeds with showing the next dialogs.
Figure 1: shipcloud example license chooser dialog
Figure 2: shipcloud example API key dialog
If you specified an evaluation license for CarrierLib now an additional dialog will show up where you have to press the "Continue" button to move on. If you have obtained a commercial license already this dialog does not appear.
Figure 2 shows the next dialog to enter the API key from shipcloud. It is recommended to use the Sandbox API key here to prevent the example from generating costs at shipcloud.
If all input has been done the example will continue in the background by performing some simple web service requests using the specified shipcloud account. Please check out the output of the example script.
![]() |
If you already have an API key feel free to edit the build-examples.xml file and insert your values. You will have to uncomment the arg |
Step 3: The shipcloud Example Step By Step
Let's take a closer look at the shipcloud example implementation. The first thing to do is to configure the CarrierLib class which is the central class of the CarrierLib library:
1 2 3 4 5 6 7 8 9 10 |
// Setup the main CarrierLib instance, get evaluation license key from Leisenfels website CarrierLib carrierlib = new CarrierLib(); carrierlib.setLicenseFile(licensefile); // Import from file // Setup shipcloud provider String baseurl = ShipcloudProvider.SHIPCLOUD_SANDBOX_BASE_URI; String version = ShipcloudProvider.SHIPCLOUD_API_V1; ShipcloudProvider provider = carrierlib.createProviderShipcloud(baseurl, version, apikey); |
Configuration of the CarrierLib (see ExampleShipcloudV1Sandbox.java)
List The Available Carriers
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
CarrierDefV1[] carriers = null; try { Object obj = provider.requestCarriers(new Hashtable<String, Object>(0)); if (obj instanceof CarrierDefV1[]) { carriers = (CarrierDefV1[]) obj; for (int i = 1; i <= carriers.length; i++) { System.out.println(" " + i + ": " + String.valueOf(carriers[i - 1])); } } } catch (Exception e) { e.printStackTrace(); } |
List the available carriers (see ExampleShipcloudV1Sandbox.java)
Get Quotes And Find Cheapest Carrier For Package
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
CarrierDefV1 targetcarrier = null; double minvalue = Double.MAX_VALUE; try { for (int i = 1; i <= carriers.length; i++) { CarrierDefV1 carrier = carriers[i - 1]; // Setup the single carrier requests Hashtable<String, Object> params = new Hashtable<String, Object>(0); params.put("carrier", carrier.getName()); params.put("service", "standard"); params.put("to_street", "Beispielstrasse"); params.put("to_street_no", "42"); params.put("to_zip_code", "22100"); params.put("to_city", "Hamburg"); params.put("to_country", "DE"); params.put("from_street", "Musterstrasse"); params.put("from_street_no", "23"); params.put("from_zip_code", "20148"); params.put("from_city", "Hamburg"); params.put("from_country", "DE"); params.put("weight", 1.5); // kg params.put("length", 20); // cm params.put("width", 20); // cm params.put("height", 20); // cm Object obj = null; try { // Single carriers may not be supported here (exceptions) obj = provider.requestShipmentQuote(params); if (obj instanceof ShipmentQuoteDefV1) { ShipmentQuoteDefV1 quote = (ShipmentQuoteDefV1) obj; String formatted = format.format(quote.getCharge()); System.out.println(" " + i + ": Charge for " + carrier + ": " + formatted + " EUR"); if (quote.getCharge() < minvalue) targetcarrier = carrier; minvalue = Math.min(minvalue, quote.getCharge()); continue; } } catch (Exception e) { // shipcloud sends HTTP status code 422 Unprocessable Entity // if a quote is not available for a certain carrier and package. //e.printStackTrace(); //System.err.println("\n shipcloud responds: " + WebRequestException.getDebugInfo(e)); // Print some extra information } System.out.println(" " + i + ": Charge for " + String.valueOf(carrier) + ": (not available)"); } } catch (Exception e) { e.printStackTrace(); } |
Find cheapest carrier based on quotes (see ExampleShipcloudV1Sandbox.java)
Create New Shipment For Carrier
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
NewShipmentDefV1 newshipmentdef = null; Hashtable<String, Object> createparams = null; // Reused for update try { createparams = new Hashtable<String, Object>(0); createparams.put("to_company", "Receiver Inc."); createparams.put("to_first_name", "Max"); createparams.put("to_last_name", "Mustermann"); createparams.put("to_street", "Beispielstrasse"); createparams.put("to_street_no", "42"); createparams.put("to_city", "Hamburg"); createparams.put("to_zip_code", "22100"); createparams.put("to_country", "DE"); createparams.put("weight", 1.5); // kg createparams.put("length", 20); // cm createparams.put("width", 20); // cm createparams.put("height", 20); // cm createparams.put("value", 123.45); createparams.put("currency", "EUR"); createparams.put("carrier", targetcarrier.getName()); createparams.put("service", "standard"); createparams.put("reference_number", "ref123456"); createparams.put("notification_email", "This email address is being protected from spambots. You need JavaScript enabled to view it."); createparams.put("create_shipping_label", false); // Not possible for sandbox system Object obj = provider.requestNewShipment(createparams); if (obj instanceof NewShipmentDefV1) newshipmentdef = (NewShipmentDefV1) obj; } catch (Exception e) { e.printStackTrace(); } |
Create new shipment (see ExampleShipcloudV1Sandbox.java)
Get The New Shipment Details
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
ShipmentDefV1 shipment = null; try { // We use the fixed version request method here to show how this can be done shipment = provider.requestShipmentDetailsV1(newshipmentdef.getId()); } catch (Exception e) { e.printStackTrace(); System.err.println("\n shipcloud responds: " + WebRequestException.getDebugInfo(e)); // Print some extra information } if (shipment != null) { System.out.print(shipment.debugPrint(" ")); } |
Shipment details (see ExampleShipcloudV1Sandbox.java)
List All Available Shipments
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
ShipmentListDefV1 allshipments = null; try { Hashtable<String, Object> params = new Hashtable<String, Object>(0); // Feel free to add filters here: //params.put("carrier", "dhl"); //params.put("service", "standard"); //params.put("reference_number", "ref123456"); //params.put("carrier_tracking_no", "43128000105"); //params.put("tracking_status", "out_for_delivery"); //params.put("page", 1); //params.put("per_page", 25); Object obj = provider.requestAllShipments(params); if (obj instanceof ShipmentListDefV1) { allshipments = (ShipmentListDefV1) obj; } } catch (Exception e) { e.printStackTrace(); System.err.println("\n shipcloud responds: " + WebRequestException.getDebugInfo(e)); // Print some extra information } if (allshipments != null) { System.out.println(" Found totally " + allshipments.getShipments().length + " shipment(s):"); int count = allshipments.getShipments().length; for (int i = 0; i < count; i++) { System.out.println("\n Shipment " + (i + 1) + " of " + count + ':'); System.out.print(allshipments.getShipments()[i].debugPrint(" ")); } } |
Available shipments at shipcloud (see ExampleShipcloudV1Sandbox.java)
Update/Modify Shipment
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
NewShipmentDefV1 updateddef = null; ShipmentDefV1 updatedshipment = null; try { // We can reuse the create params here, add second package for the shipment (package change is not possible) createparams.put("id", newshipmentdef.getId()); createparams.put("weight", 3.0); // kg createparams.put("length", 40); // cm createparams.put("width", 40); // cm createparams.put("height", 40); // cm // Omit value here Object obj = provider.requestUpdateShipment(createparams); if (obj instanceof NewShipmentDefV1) { updateddef = (NewShipmentDefV1) obj; // Get shipment details again updatedshipment = provider.requestShipmentDetailsV1(newshipmentdef.getId()); } } catch (Exception e) { e.printStackTrace(); System.err.println("\n shipcloud responds: " + WebRequestException.getDebugInfo(e)); // Print some extra information } if (updateddef != null && updatedshipment != null) { System.out.println(" Successful!"); System.out.println("\nReading the updated shipment details:"); System.out.print(updatedshipment.debugPrint(" ")); } |
Updating a shipment (see ExampleShipcloudV1Sandbox.java)
Delete Shipment
1 2 3 4 5 6 7 8 9 10 11 12 13 |
boolean success = false; try { Hashtable<String, Object> params = new Hashtable<String, Object>(0); params.put("id", newshipmentdef.getId()); success = provider.requestDeleteShipment(params); } catch (Exception e) { e.printStackTrace(); System.err.println("\n shipcloud responds: " + WebRequestException.getDebugInfo(e)); // Print some extra information } |
Delete shipment at shipcloud (and carrier) (see ExampleShipcloudV1Sandbox.java)