Java and Javascript Archive

The NCBI QBLAST Package

• How You Can Test Electronic Components

NCBI provides a standardized API called URLAPI to formulate and dispatch direct HTTP-encoded requests to the NCBI QBlast system. The URLAPI provides a URL and a mechanism to set parameters that allows users to send sequences for BLAST searches.

NCBI QBlast works through 4 steps:

1. The user provides BLAST parameters through a URL using the HTTP POST method
2. The QBlast service returns a Request Identifier (RID) and a Request Time of Execution (RTOE, measured in seconds) for the search, which provide respectively, a unique identifier for the search operation and an estimate of the time required to complete the search
3. The user queries the QBlast service with the RID through HTTP GET method
4. The server sends back the result with a status value that indicates the progress of the BLAST request

Users of the QBlast service should adhere to the guidelines provided by NCBI when submitting large batch searches. In general, searches should be performed in a sequential manner after receiving the RID and RTOE for each submission. NCBI specifies that each request be submitted after a pause of no less than 3 seconds to check on the status of the request using the RID. Failure to do so may overload the server and force NCBI to block offending users from further use of the service.

Strategy for Creating a QBlast Based System

The design of the NCBI QBlast service as described above stipulates the need for a client application that performs the following operations:

1. Send search requests made by the user and check the status of requests periodically
2. Perform the appropriate action based on the nature of the status value that gets returned

QBlast may return one of three types of status values: "READY" meaing that the search was completed successfully, "WAITING" meaning that the search has not been completed and "UNKNOWN" meaning that an error has been encountered during the BLAST submission and/or search process. In UML terms, the user and the client application are actors that interact with the QBlast system. The UML diagram below (Fig. 3.1) depicts the use cases that encapsulate the basic functionality that is desired of the system that we wish to create:

1. User submits query sequence to the QBlast service
2. Application queries status of the BLAST search with a unique RID
3. Applcation returns results approriate to the status value

Fig. 3.1. Use Cases for the QBlast service

In terms of the architecture of the application, we will provide a class that will wrap the NCBI URLAPI into Java API that can be reused in other applications. To fulfill these use cases, we will design the QBlast service to implement 2 methods: submitQuery and querystatus (Fig. 3.2).

Fig. 3.2. Class QBlast

The QBlast class is our interface to the real NCBI URLAPI. From the application point of view, it is totally transparent and is designed to be so in order to accommodate and simplify future changes to the API (or, if there is a need to adopt an entirely different API). This design ensures that the framework we create remains usable even if the underlying API requires changes. The submitQuery () method takes the BLAST

parameters (specified through the QBlastParameter object) and returns an object of type Requestidentifier. The parameters needed to run the BLAST search would be obtained from the user through the SwingBlast GUI we created in Chapter 1. The Requestidentifier is returned by the QBlast service in response to the submitted request and contains the RID and the RTOE for a specific search.

For the queryStatus method similarly, we will need 2 objects: Requestidentifier and QBlastResult. A UML diagram with these considerations in mind is shown in Fig. 3.3.

OB last

+sul>m tQuery(param etei BlustFormFiirart) efer): Requestl denti fer +quei y Status (rid: R equestl denti tier): Q BLastR esult

Requestidentifier

-rid String -i1oe int

QBLastResult

-statlis String -i esultSt! ing

BlastF of rrpara meter

Fig. 3.3. UML class diagram showing the QBlast architecture

Designing the BLAST API

We will design our BLAST API to consist of 3 classes:

• Blast
• BlastManager
• BlastException

We will define Blast as an abstract class, which means that it represents an abstract concept, and therefore cannot be instantiated, but can only be subclassed. An abstract class is declared using the keyword abstract before the class keyword in the class declaration. In this case, for example, we would declare the Blast class as shown below:

We'll describe this class in detail later in the Chapter. The BlastManager class provides a mechanism to get an instance of the abstract class Blast without having to worry about how to create the instance by calling the static method (that we had earlier explained in Chapter 2):

Blast blast = BlastManager.createBlast();

The BlastException class provides a mechanism for handling exceptions thrown by any implementation when a failure or error occurs. The Request identifier class is a Java class, which provides what are known as setter, and getter methods that provide information about the request submitted to the Blast service. What are setter and getter methods? In a class definition, private fields can be encapsulated so that the data structure used can be changed at will without compromising the rest of the code that uses that class. When the data structure is hidden, the way to provide access to and/or modify the fields is through setter and getter methods. For example, a class that has a field called result will provide a setter method called setResult and a getter method call getResult. The Requestidentif ier class uses these methods as described above. The structure of the application designed so far is shown in Fig. 3.4.

0 0