Manual del programador de l'api MobileHTTPConnection

Què és MobileHTTPConnection

L'API MobileHTTPConnection és una interfície d'ús senzill per programadors de J2ME que vulguin connectar-se a una base de dades i executar sentències SQL sobre la mateixa.
Aquesta API gestiona la connexió de forma asíncrona, de manera que quan es faci una crida, no caldrà estar esperant a que aquesta rebi la resposta del servidor, sinó que quan el programador ho desitgi demanarà el resultat obtingut o si està connectat o desconnectat a la base de dades, i si el resultat encara no està disponible, podrà tornar més tard a recuperar-lo.

Com utilitzar l'API

L'API consta del mètode constructor i de 7 funcions bàsiques:

- A la constructora se li passen els paràmetres que es necessiten per connectar-se a la base de dades: ip a on està el servidor proxy, nom de la base de dades, usuari i password per accedir a la base de dades.
- DBConnectionRequest (): Envia al servidor la petició d'obrir la base de dades. Aquest mètode llença una excepció si la base de dades especificada ja ha estat oberta o si la connexió s'ha perdut.
- DBOpened (): Mira si la base de dades està oberta o no. Aquest mètode llença una excepció si el mètode DBConnectionRequest no ha estat cridat prèviament, si el servidor ha trobat problemes mentre s'obria la base de dades o si la connexió s'ha perdut.
- DBStatement (sentència SQL): Envia la sentència SQL desitjada al servidor. Aquesta funció retorna un número o tiquet que és que s'ha de presentar quan es vol obtenir el resultat. Aquest mètode llença una excepció si la base de dades no ha estat oberta prèviament o si la connexió s'ha perdut.
- DBResultRequest (tiquet): Retorna el resultat associat al tiquet en forma de MobileHTTPStatementResult. Aquest mètode llença una excepció si la base de dades no ha estat oberta prèviament o si la connexió s'ha perdut.
- DBClose (): Envia al servidor la petició de tancar la base de dades. Aquest mètode llença una excepció si la base de dades no ha estat oberta prèviament o si la connexió s'ha perdut.
- DBClosed (): Mira si la base de dades està tancada o no. Aquest mètode llença una excepció si el mètode DBClose no ha estat cridat prèviament, si el servidor ha trobat problemes mentre es tancava la base de dades o si la connexió s'ha perdut.
- DBReinit (): En cas que hi hagi hagut una pèrdua de la connexió, s'haurà de cridar aquest mètode per reinicialitzar l'API i tornar a començar des del principi.

La classe MobileHTTPException representa les excepcions comentades anteriorment.
Aquesta classe té 2 mètodes:
- getCode(): que retorna el codi associat a l'excepció.
- getMessage(): que retorna el missatge associat a l'excepció.
L'excepció associada a la pèrdua de connexió té codi -1, per tant, quant es faci un catch d'una excepció s'ha de verificar si el codi de la mateixa és -1. En cas que ho sigui, s'ha de cridar el mètode DBReinit() i fer el necessari a la midlet per tornar a cridar el mètode DBConnectionRequest.

MobileHTTPStatementResult és una representació del resultat obtingut d'una sentència SQL, que aconseguim quan cridem a DBResultRequest(tiquet). A més aquesta classe crearà una J2METable anomenada SDLIB_temp_table que serà una vista materialitzada del resultat.
Quan tenim la instància de MobileHTTPResultRequest el primer que hem de fer és preguntar per l'estat del resultat (getStatus()), per saber si està en espera (MobileHTTPResultRequest.WAITING), si el resultat està disponible i és correcte (MobileHTTPResultRequest.OK) o bé si el resultat està disponible, però ha estat un error (MobileHTTPResultRequest.KO).
A partir d'aquí MobileHTTPResultRequest té diversos mètodes que donen tota la informació necessària sobre el resultat.
Quan un resultat ja no estigui en espera hi ha diverses opcions:

- Si l'estat és MobileHTTPResultRequest.KO, llavors el resultat és un error. En aquest cas obtindrem el missatge d'error cridant a getErrorMessage().

- Si l'estat és MobileHTTPResultRequest.OK, el resultat pot venir d'una consulta (que ho sabrem cridant a isSelect()) o bé d'una actualització (que ho sabrem cridant a isWrite()).

- Si és una consulta, podrem obtenir les dades utilitzant els següents mètodes:
-getStringResult(): que retornarà una matriu d'Strings, amb el resultat de la consulta.
- getCols(): que retornarà el número de columnes.
- getRows(): que retornarà el número de files.
- getColumnLength(): que retornarà en un vector d'enters les longituds màximes de les columnes.
- getColumnTypes(): que retornarà en un vector d'Strings els tipus de les columnes.
- getColumnNames(): que retornarà en un vector d'Strings els noms de les columnes.

- Si és una actualització, podrem obtenir les dades utilitzant els següents mètodes:
- getRows(): que retornarà el número de files afectades.


En tot tipus de resultats, sempre podrem veure la sentència SQL a la qual estan associats mitjançant el mètode getStatement().