Skip Navigation
  1. BlackBerry Docs
  2. BlackBerry Web Services 12.10
  3. Blackberry Web Services Development Guide
  4. Using BlackBerry Web Services APIs
  5. Sample walkthrough: Creating a user account
  6. Initializing and authenticating with the BlackBerry Web Services SOAP APIs

Initializing and authenticating with the 
BlackBerry Web Services
 SOAP APIs

Before an application can make calls to the 
BlackBerry Web Services
 SOAP APIs, the application must initialize the BWS and BWSUtil web services.
When the BWS and BWSUtil web services are initialized, they accept subsequent API calls from the application. If initialization or authentication of a request are not successful, the application throws an exception. The exception contains a simple text message property that your application can access for more information.

Define metadata

Each method call contains a metadata object that specifies locale, client version, and organization ID data. The inclusion of this metadata helps supports compatibility with different versions of 
BlackBerry Web Services
. To learn more about metadata such as the 
ClientVersion
, 
Locale
, and 
OrgUid
, see the API Reference.
Here's an example of how to create the 
RequestMetadata
 object and declare the variables used for authentication: 
// The request metadata information.
// This is the version of the WSDL used to generate the proxy, not the version of the server.
private final static String CLIENT_VERSION = "12.6.0";

// To use a different locale, call getLocales() in the BWSUtilService web service
// to see which locales are supported.
private final static String LOCALE = "en_US";
private final static String ORG_UID = "0";
private final static RequestMetadata REQUEST_METADATA = new RequestMetadata();

// Authentication type name.
private final static String AUTHENTICATOR_NAME = "BlackBerry Administration Service";

// Hostname to use when connecting to web service. Includes port 
private static String BWS_HOST_NAME = null; // e.g. BWS_HOST_NAME = "server01.yourcompany.net:18084"
private static String USERNAME = null; // e.g. USERNAME = "admin"
private static String PASSWORD = null; // e.g. PASSWORD = "password"
To send requests, you must provide authentication info, including the host name, user name, and password values.
// Hostname to use when connecting to web service.
BWS_HOST_NAME = "<BWSHostName>"; // e.g. BWS_HOST_NAME = "server01.yourcompany.net".
USERNAME = "<username>"; // e.g. USERNAME = "admin".
PASSWORD = "<password>"; // e.g. PASSWORD = "password".

Assign values to the Metadata object

Here's how to set the client version, locale, and organization ID of the metadata object that was previously created:
REQUEST_METADATA.setClientVersion(CLIENT_VERSION);
REQUEST_METADATA.setLocale(LOCALE);
REQUEST_METADATA.setOrganizationUid(ORG_UID);

Initialize and set the URL properties of the web services

Next, you initialize and set the values for the URL properties of the web services so that the application can connect to the 
BlackBerry Web Services
.
URL bwsServiceUrl = null;
URL bwsUtilServiceUrl = null;

try
{
    // These are the URLs that point to the web services used for all calls.
    bwsServiceUrl = new URL("https://" + BWS_HOST_NAME + "/enterprise/admin/ws");
    bwsUtilServiceUrl = new URL("https://" + BWS_HOST_NAME + "/enterprise/admin/util/ws");
}
catch (MalformedURLException e)
{
    logMessage("Cannot initialize web service URLs");
    logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue);
    return returnValue;
}

// Initialize the BWS web service stubs that will be used for all calls.
logMessage("Initializing BWS web service stub");
QName serviceBWS = new QName("http://ws.rim.com/enterprise/admin", "BWSService");
QName portBWS = new QName("http://ws.rim.com/enterprise/admin", "BWS");
_bwsService = new BWSService(null, serviceBWS);
_bwsService.addPort(portBWS, "http://schemas.xmlsoap.org/soap/", bwsServiceUrl.toString());
_bws = _bwsService.getPort(portBWS,BWS.class);
logMessage("BWS web service stub initialized");

logMessage("Initializing BWSUtil web service stub");
QName serviceUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtilService");
QName portUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtil");
_bwsUtilService = new BWSUtilService(null, serviceUtil);
_bwsUtilService.addPort(portUtil, "http://schemas.xmlsoap.org/soap/", bwsUtilServiceUrl.toString());
_bwsUtil = _bwsUtilService.getPort(portUtil, BWSUtil.class);
logMessage("BWSUtil web service stub initialized");

// Set the connection timeout to 60 seconds.
HTTPClientPolicy httpClientPolicy = new HTTPClientPolicy();
httpClientPolicy.setConnectionTimeout(60000);

httpClientPolicy.setAllowChunking(false);
httpClientPolicy.setReceiveTimeout(60000);

Client client = ClientProxy.getClient(_bws);
HTTPConduit http = (HTTPConduit) client.getConduit();
http.setClient(httpClientPolicy);

client = ClientProxy.getClient(_bwsUtil);
http = (HTTPConduit) client.getConduit();
http.setClient(httpClientPolicy);

Define the authenticator object

The following code defines the 
Authenticator
 object that the application requires for the initialization and authentication process. In the sections that follow, the application uses the authenticator object to collect the login information and the encoded user name that the application uses to authenticate with the 
BlackBerry Web Services
.
Authenticator authenticator = getAuthenticator(AUTHENTICATOR_NAME);
if (authenticator != null)
{
    String encodedUsername = getEncodedUserName(USERNAME, authenticator);
    if (encodedUsername != null && !encodedUsername.isEmpty())
    {
        /*
        * Set the HTTP basic authentication on the BWS service.
        * BWSUtilService is a utility web service that does not require
        * authentication.
        */
        BindingProvider bp = (BindingProvider) _bws;
        bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, encodedUsername);
        bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, PASSWORD);

        returnValue = true;
    }
    else
    {
        logMessage("'encodedUsername' is null or empty");
    }
}
else
{
    logMessage("'authenticator' is null");
}

Authenticate with the 
BlackBerry Web Services

After the 
Authenticator
 object is created, here's how to retrieve the encoded login information for the administrator account that the app uses, and authenticate the app with the 
BlackBerry Web Services
.
public static String getEncodedUserName(String username, Authenticator authenticator)
{
    final String METHOD_NAME = "getEncodedUserName()";
    final String BWS_API_NAME = "_bwsUtil.getEncodedUsername()";
    logMessage("Entering %s", METHOD_NAME);
    String returnValue = null;

    GetEncodedUsernameRequest request = new GetEncodedUsernameRequest();
    request.setMetadata(REQUEST_METADATA);
    request.setUsername(username);
    request.setOrgUid(REQUEST_METADATA.getOrganizationUid());
    request.setAuthenticator(authenticator);

    CredentialType credentialType = new CredentialType();
    credentialType.setPASSWORD(true);
    credentialType.setValue("PASSWORD");
    request.setCredentialType(credentialType);

    GetEncodedUsernameResponse response=null;
    try
    {
        logRequest(BWS_API_NAME);
        response = _bwsUtil.getEncodedUsername(request);
        logResponse(BWS_API_NAME, response.getReturnStatus().getCode(), response.getMetadata());
    }
    catch (WebServiceException e)
    {
        // Log and re-throw exception.
        logMessage("Exiting %s with exception \"%s\"", METHOD_NAME, e.getMessage());
        throw e;
    }

    if (response.getReturnStatus().getCode().equals("SUCCESS"))
    {
        returnValue = response.getEncodedUsername();
    }
    else
    {
        logMessage("Error Message: \"%s\"", response.getReturnStatus().getMessage());
    }

    if (Base64.isBase64(returnValue))
    {
        logMessage("Decoded value of encoded username \"%s\"", 
        StringUtils.newStringUtf8(Base64.decodeBase64(returnValue)));
    }
    else
    {
        logMessage("Value of encoded username \"%s\"", returnValue);
    }
    logMessage("Exiting %s", METHOD_NAME);
    return returnValue;
}
When the app completes the initialization and authentication process, the 
BlackBerry Web Services
 are ready to accept API calls from the application.