The AFD Java API makes using address management and bank validation in Java easy, minimising your work to get an integration up and running quickly, while also providing full flexibility to customise it to your requirements. Regardless of how you are using it our Java package makes integration with your application simple.

Introduction

This guide is intended to assist you in getting started with using Robot with any Java application. It is recommended you read this guide first and then refer to the main manual for advanced settings, if desired, once you have it working.

Setup

To use AFD Robot API you first need to install an AFD product (Windows only) or have access to an Evolution server (Java as a client is then completely platform independent). For Windows development and testing you can download data-restricted evaluation products from our website's evaluation page.

To use AFD Robot API in your Java project simply add the afd.api package (afdapi.jar) to your project

Eclipse:

Right click your Project, select Build Path -> Configure Build Path. Under the Libaries Tab, click Add External JARs and browse to the

To do this, right click the References item under your project in Solution Explorer select “Add Reference”, and use the Browse Tab to browse to the library file. If you right click and go to Properties you can also select the “Javadoc in archive” option and browse to the docs folder of the jar file to obtain context sensitive documentation in Eclipse.

NetBeans:

Go to project properties (right click on the project). Click on the Libraries Tab and in turn the Compile Tab.

Click the “Add JAR/Folder” button and browse for the library file.

If using a localling installed product on Windows the native libraries (javaAFDAPI32.dll and javaAFDAPI64.dll) will also need to reside in your Java library path (includes your Windows PATH environment variable so can be placed in any listed location).

Creating an Instance of the Robot Class

You can quickly and easily add Address Management functionality to your application with the following steps:

  1. Add the following line to the top of your java file:

    import afd.api.*;
    
  2. To create an instance of the Robot class add the following line to your code:

    Robot robot = new Robot(RobotType.ADDRESS);
    

    (You can also use RobotType.Bank or RobotType.Email if wanting to carry out Bank or Email Validation). If you wish to mix Address, Bank and/or Email validation simply create multiple instances of the Robot class.

  3. If using an evolution server rather than a locally installed product set the Authentication property to an instance of the Authentication class for your server, e.g.:

    robot.setAuthentication(new Authentication("http://myserver:81","333333", "password", "RobotAPI"));
    

    You should replace myserver:81 with the name of your server and port, 333333 with your AFD Serial number and password with your password.

  4. If using a locally installed product on Windows and you wish to specify the location for the native library call setLibraryPath to do so, e.g.:

    robot.setLibraryPath("C:\\mylibrarypath\\");
    

Task Reference for Robot Class

Address Lookup (Postcode and Fast-Find)

To find an address record from the postcode or any fragment of the address use the find method on an instance of the Robot class with the lookup string you wish to use and one of the following operations:

  • Operation.FASTFIND_LOOKUP – Looks up the supplied string which can be a postcode or any fragment of the address.
  • Operation.POSTCODE_LOOKUP – Looks up a supplied postcode
  • Operation.POSTCODE_PROPERTY_LOOKUP – Looks up up a supplied postcode which optionally may also include a property, e.g. “279, B11 1AA”

This will return:

  • > 0 The number of results found
  • < 0 No results have been found (-2) or an error has occurred (use getLastErrorText to obtain a human readable message for the error).

You can then iterate through the robot.Records collection to process each result in your application. This collection has the method getField(string) which you can use to return any of the fields for the result.

For example:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.ADDRESS);
// Set authentication options for evolution if required
//robot.setAuthentication(new Authentication("http://myserver:81",
// "333333", "password", "RobotAPI"));
// Lookup the records
int results = robot.find("b11 1aa", Operation.FASTFIND_LOOKUP);
// Check for error
if (results < 0) {
 System.out.println(robot.getLastErrorText());
 return;
}
// Iterate through results
for (Record record : robot.Records) {
 // Obtain the fields you require – some examples:
 String list = record.getField("List");
 String organisation = record.getField("Organisation");
 String property = record.getField("Property");
 String street = record.getField("Street");
 String locality = record.getField("Locality");
 String town = record.getField("Town");
 String postcode = record.getField("Postcode");
 // display a string for the result
 // - replace with a function to process the result in your application?
 System.out.println(list);
}

The number of results returned for FastFind operations will be limited by the MaxRecords and Timeout Properties of the Robot class instance.

To carry out a search for an Address:

  • Call clear to Clear any current address fields.
  • Use the setField method to set the value of each field you wish to search
  • Call find with Operation.Search (the Lookup parameter will be ignored)

The find function will return:

  • > 0 The number of results found
  • < 0 No results have been found (-2) or an error has occurred (use LastErrorText to obtain a human readable message for the error).

You can then iterate through the robot.Records collection to process each result in your application. This collection has the method getField(string) which you can use to return any of the fields for the result.

For example:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.ADDRESS);
// Set authentication options for evolution if required
//robot.setAuthentication(new Authentication("http://myserver:81",
// "333333", "password", "RobotAPI"));
// Set the fields to Search
robot.clear();
robot.setField("street", "Commercial Street");
robot.setField("town", "Birmingham");
// Lookup the records
int results = robot.find(null, Operation.SEARCH);
// Check for error
if (results < 0) {
 System.out.println(robot.getLastErrorText());
 return;
}
// Iterate through results
for (Record record : robot.Records) {
 // Obtain the fields you require – some examples:
 String list = record.getField("List");
 String organisation = record.getField("Organisation");
 String property = record.getField("Property");
 String street = record.getField("Street");
 String locality = record.getField("Locality");
 String town = record.getField("Town");
 String postcode = record.getField("Postcode");
 // display a string for the result
 // - replace with a function to process the result in your application?
 System.out.println(list);
}

The number of results returned for Search operations will be limited by the MaxRecords`s and Timeout Properties of the Robot class instance.

Bank records can be looked up or searched for in exactly the same way as Address records (see section 3.2.1 and Section 3.2.2). The difference being that the Robot class must be instantiated with a parameter of RobotType.BANK rather than RobotType.ADDRESS.

The applicable operations are:

  • Operation.FASTFIND_LOOKUP –Looks up the supplied string which can be a sortcode, bank/branch name, location, STD Code or BIC.
  • Operation.SEARCH – Search for results matching the search fields specified using the SetField method.

An example of a Bank Lookup:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.BANK);
// Set authentication options for evolution if required
//robot.setAuthentication(new Authentication("http://myserver:81", "333333",
"password", "RobotAPI"));
// Lookup the records
int results = robot.find("560036", Operation.FASTFIND_LOOKUP);
// Check for error
if (results < 0) {
 System.out.println(robot.getLastErrorText());
 return;
}
// Iterate through results
for (Record record : robot.Records) {
 // Obtain the fields you require – some examples:
 String list = record.getField("List");
 String sortcode = record.getField("SortCode");
 String ownerBankFullName = record.getField("OwnerBankFullName");
 String branchTitle = record.getField("FullBranchTitle");
 String location = record.getField("Location");
 String directDebits = record.getField("BACSDirectDebits");
 // display a string for the result
 // - replace with a function to process the result in your application?
 System.out.println(list);
}

Bank Account Validation

To validate an account number use the setField method to set the value of the sort code and account number (alternatively the IBAN can be used)

You may also wish to set the clearing system if you want to restrict validation to the UK (BACS), or Irish (IPSO) systems only.

Call find with Operation.VALIDATE_ACCOUNT (the Lookup parameter will be ignored)

Following successful validation a single record will be returned. It is recommended you use the sortcode and account number returned rather than that you supplied as non-standard length account numbers will be transcribed for you.

An example of a Bank Account Validation:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.BANK);
// Set authentication options for evolution if required
//robot.setAuthentication(new Authentication("http://myserver:81", "333333",
"password", "RobotAPI"));
// Set the Account Details to validate
robot.clear();
robot.setField("SortCode", "774814");
robot.setField("AccountNumber", "24782346");
// RollNumber can also be set if applicable, IBAN can also be validated instead
// Validate the Account Details
int results = robot.find(null, Operation.ACCOUNT_VALIDATE);
// Check for error, e.g. invalid account number
if (results < 0) {
 System.out.println(robot.getLastErrorText());
 return;
}
// Success will return a single result
String sortcode = robot.getField("SortCode");
String accountNumber = robot.getField("AccountNumber");
String iban = robot.getField("IBAN");
String rollNumber = robot.getField("RollNumber");
String typeOfAccount = robot.getField("TypeOfAccount");
String clearingSystem = robot.getField("ClearingSystem");
System.out.println("Account Number is Valid");

Card Number Validation

To validate a debit or credit card number use the setField method to set the value of the card number and optionally expiry date. (The expiry date is checked that it is in range for the current date if provided).

Call find with Operation.VALIDATE_CARD (the Lookup parameter will be ignored).

Following successful validation a single record will be returned.

An example of Card Number Validation:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.BANK);
// Set authentication options for evolution if required
//robot.setAuthentication(new Authentication("http://myserver:81", "333333", "password", "RobotAPI"));
// Set the field to validate
robot.Clear();
robot.SetField("cardnumber", "4694782385016585");
robot.SetField("expirydate", "10/17"); // This field is optional
// Validate the Card Details
int results = robot.find(null, operation.CARD_VALIDATE);
// Check for error, e.g. invalid account number
if (results < 0) {
 System.out.println(robot.getLastErrorText());
 return;
}
// Success will return a single result
String cardType = robot.getField("CardType");
System.out.println("Valid: " + cardType);

Email Validation

To validate an email address from an instance of the robot class instianted with RobotType.EMAIL simply call the find method with the email address to validate and Operation.EMAIL_VALIDATE.

An example of Email Address Validation:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.EMAIL);
// Set authentication options for evolution if required
//robot.setAuthentication(new Authentication("http://myserver:81", "333333", "password", "RobotAPI"));
// Validate the Email Address
int results = robot.find("support@afd.co.uk", Operation.EMAIL_VALIDATE);
// Check for error, e.g. invalid Email Address
if (results < 0) {
 System.out.println(robot.getLastErrorText());
 return;
}
// Email Address is Valid
System.out.println("Email Address is Valid");

Statelessly Retrieving Previous Records

If you have returned results following an address or bank lookup or search and require to fetch one of those results again you can do this with a Retrieve operation. An example when you might wish to do this if is returning a list of results to the user, wanting to minimise data passed and then need to retrieve the full record when a user selects an individual record.

To do this you need to store the key (use getField(“Key”) to obtain this) when processing the original record.

Please note that this Key is unique in a particular dataset so can be used statelessly or across multiple servers as long as the same version of the data is still in use. It is not unique across future versions of the data and therefore should not be stored in a database as a unique reference.

To retrieve a record call find with the key for the record specified in the lookup field and an Operation of Operation.RETRIEVE.

A single result will be returned which you can then process.

This will return:

  • 1 The single result was found
  • < 0 No results have been found (-2) or an error has occurred (use LastErrorText to obtain a human readable message for the error).

For example:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.RETRIEVE);
// Set authentication options for evolution if required
//robot.setAuthentication(new Authentication("http://myserver:81", "333333", "password", "RobotAPI"));
// Lookup the records
int results = robot.find("B11 1AA1001", Operation.RETRIEVE);
// Check for error
if (results < 0) {
System.out.println(robot.getLastErrorText());
return;
}
// Obtain the fields you require – some examples:
String organisation = robot.getField("Organisation");
String property = robot.getField("Property");
String street = robot.getField("Street");
String locality = robot.getField("Locality");
String town = robot.getField("Town");
String postcode = robot.getField("Postcode");

Calling off results individually

For ease of use the find method used in the previous sections returns all results at once until a pre-determined timeout or maximum record count is reached (if applicable). When used with an evolution server there is little point to doing anything else as results have to result from the same web request.

However in some cases when using an installed product, you may wish to return results one-by-one as they are called off or provide your own mechanism for determining when to abort a search (for example based on the actual results that come back).

In such scenarios rather than calling find, you can call the findFirst and findNext methods. findFirst has identical parameters to find but rather than returning the results in the Records List, it instead returns one result at a time (findNext takes no parameters).

You do also need to be aware that findFirst and/or findNext will sometimes return a value of 0 indicating a record or sector break which is provided to give the opportunity to cancel long searches and at which point no new result will be returned.

An example of an Address Fast-Find, identical that given in section 4.2.1 but using findFirst and findNext is as follows:

// Create instance of the Robot class
Robot robot = new Robot(RobotType.Address);
// Lookup the records
int result = robot.findFirst("b11 1aa", Operation.FASTFIND_LOOKUP);
// Check for Error, but note if 0 has been returned it is still possible no
results will be found
if (result < 0) {
    System.out.println(robot.getLastErrorText());
    return;
}
// Process and call off each result
long results = 0;
    while (result >= 0) {
    if (result > 0) {
        // obtain some of the fields for the result to use in your application
        String list = robot.getField("List");
        String organisation = robot.getField("Organisation");
        String property = robot.getField("Property");
        String street = robot.getField("Street");
        String locality = robot.getField("Locality");
        String town = robot.getField("Town");
        String postcode = robot.getField("Postcode");
        // display a string for the result
        // - replace with a function to process the result in your application?
        System.out.println(list);
        results++;
        }
    else if (result == 0) {
        // sector or record break – take the chance to allow user to cancel?
    }
    // set your own condition(s) to abort the search
    if (results > 500) break;
    result = robot.findNext();
}
if (results > 0) {
    // success
}
else {
    System.out.println("No Results Found");
}

Additional Properties and Functions for Robot

Robot contains many other properties and functions, for example you can alter the timeout, maximum number of records returned or use FindFirst and FindNext to call of records individually. For full details of these please see section 4 of the main Robot Java API guide.