Get started with the BlackBerry Administration API

by Retired ‎02-18-2010 03:32 PM - edited ‎09-20-2010 10:24 AM (6,766 Views)

Summary

 

This article applies to the following:

  • BlackBerry® Administration application programming interface (API)
  • BlackBerry® Enterprise Server software version 5.0
  • Java® integrated development environments (IDEs)
  • Microsoft® Visual Studio® .NET

Details

 

The BlackBerry Administration API introduced with BlackBerry Enterprise Server software version 5.0 allows the BlackBerry Administration Service to be controlled using web service calls.

 

The BlackBerry Administration API is a BlackBerry Enterprise Server component that is installed on the server that hosts the BlackBerry Administration Service. The BlackBerry Administration API is based on web services that receive API calls from client applications and translates requests into a form that the BlackBerry Administration Service can process.

 

There are two common IDEs you can use to develop applications with the BlackBerry Administration API. For Java application development, you can use Eclipse® and for Microsoft® Visual C#® development you can use Microsoft Visual Studio .NET.

 

Choosing a development platform

 

To provide API methods that meet the needs of the different BlackBerry Enterprise Server components, the BlackBerry Administration API classes use polymorphic data objects. These objects are data type extensions that inherit the properties of a parent class, but contain data that is managed by a specific BlackBerry Enterprise Server component. Using polymorphic data objects allows you to add or remove features from your application as you add or remove components from the BlackBerry Enterprise Server.

 

Data type extensions are not currently supported by all web service frameworks. If you are developing in Java, to make sure that your platform supports data type extensions you should choose a platform and framework that support Java Architecture for XML Binding (JAXB) 2.1 and @XMLSeeAlso annotation. If you are developing in Microsoft® .NET Framework or any other language, your platform must support XML Schema Definition (XSD) type extensions. The following frameworks support the data type extension requirements of the BlackBerry Administration API:

  • Microsoft Visual Studio .NET, all Microsoft .NET Framework languages
  • Apache CXF™ 2.1.1
  • Java API for XML Web Services (JAX-WS) RI (Reference Implementation) 2.1.4

Installing the SSL certificate on your development computer

 

Before you can generate the proxy you must first install the Secure Sockets Layer (SSL) certificate on your development computer. The BlackBerry Administration API shares the SSL certificate used by the BlackBerry Administration Service. By default, the BlackBerry Administration Service uses a self-signed certificate. If you have not replaced the self-signed certificate on the BlackBerry Administration Service in your development environment with a certificate signed by a certificate authority, you can install the certificate in the Trusted Root Certificate Authorities key store using Microsoft® Internet Explorer®.

 

If you are developing in Microsoft .NET Framework, Microsoft® Visual Studio® can access the self-signed certificate in the key store used by Microsoft Internet Explorer so your environment should not require further configuration. If you are developing in Java, you can use Microsoft Internet Explorer to export a self-signed certificate used by the BlackBerry Administration Service and add the certificate to your own key store. For example, Apache CXF contains a key  store generator called keytool.

 

Generating a client proxy for the web services

 

The BlackBerry Administration API includes several web services and each web service is associated with a Web Services Description Language (WSDL) definition. You can use a proxy generator to specify the web references for each WSDL definition and automatically generate the classes in your project. For certain API calls, such as creating a BlackBerry smartphone user account, objects need to be transferred from one web service to another. To make sure that you do not have multiple copies of the same data types in your project, you should generate a single client proxy using a command line proxy generator. The proxy will only contain one copy of the object that is shared among multiple web services.

 

This proxy will be generated differently depending on the development environment being used but will produce essentially the same result, a list of the available APIs and web service calls that can be used to communicate with the BlackBerry Enterprise Server.

 

Microsoft Visual Studio includes a compatible proxy generator called wsdl.exe, Apache CXF includes a proxy generator called wsdl2java, and JAX-WS RI includes a proxy generator called WSimport.


Sample version  Suggested framework  Interface  Same application and ReadMe files 
Java Apache CXF Console Java sample*
Microsoft Visual C# Microsoft .NET Framework Console C# sample

 

*This Java sample was created to work with a Proxy generated with Apache CXF version 2.2.1 specifically. Different versions of CXF may generate the proxy in a slightly different manner such as slightly different package names and a few small parameter changes. Eclipse is intuitive enough to point out where this will be causing problems in the TestMain.java file and will usually offer quick-fix options to resolve the errors for you.

 

Note: The BlackBerry Administration API for BlackBerry Enterprise Server software version 5.0 can be downloaded for installation at http://na.blackberry.com/eng/developers/resources/adminapi.jsp.