ACPapi používateľská príručka

Funkcia aplikačného rozhrania

Aplikačné rozhranie pre obsluhu protokolu ACP (ACPapi) slúži na uľahčenie prác programátorov pri tvorbe aplikácií, ktoré sú závislé na reálno-časových údajoch sieťovej prevádzky. Jej hlavnou funkciou je obsluhovanie protokolu ACP, ktorá umožňuje komunikáciu medzi Kolektorom a Analyzérom, pričom sa už o implementačné detaily prebiehania tejto komunikácie programátor nemusí starať. ACPapi je implementované v jazyku Java.

Celý proces získavania dát pomocou ACPapi sa dá znázorniť nasledovne:

ANALYZÉR < = (ACPapi) = > KOLKEKTOR < = EXPORTÉR < = SIEŤ

Aplikačné rozhranie tiež poskytuje výhodu ľahkej implementácie protokolu ACP v iných projektoch.

Súpis obsahu dodávky

Program je dodávaný na jednom inštalačnom CD médiu, ktoré obsahuje nasledujúce súčasti:

• zdrojové súbory aplikačného rozhrania
• súbor ACPapi vo formáte Java archive (jar), ktorý predstavuje aplikačné rozhranie
• knižnice potrebné pre prácu s aplikačným rozhraním
• dokumentáciu zloženú z:
  • bakalárskej práce (vo formáte PDF)
  • systémovej príručky (PDF)
  • tejto používateľskej príručky (PDF)
  • príručky špecifikácie protokolu ACP (PDF)
  • systémovej dokumentácie tried - javadoc vo formáte HTML

Inštalácia aplikačného rozhrania

Požiadavky na technické prostriedky

ACPapi spĺňa svoj účel až v spojení s nejakou aplikáciou, a preto, je ťažké predpokladať jeho technické požiadavky. Pre spoľahlivý beh samotného aplikačného rozhrania sa vyžaduje nasledovná hardvérová konfigurácia:

• procesor s architektúrou i386
• 128 MB operačnej pamäte (jej veľkosť závisí od množstva a rýchlosti spracovania prenesených dát)
• 40 MB voľného miesta na pevnom disku
• grafická karta novej generácie s minimálne 64MB pamäťou
• sieťová karta 100Mbit/s

Požiadavky na technické prostriedky sa líšia v závislosti od množstva súčasne bežiacich meraní, počtu spojení s Kolektormi, zložitosti nastavených filtračných kritérií a spôsobe prijímania dát prostredníctvom ACPapi. Monitorovanie rozsiahlejšej siete (napr. sieť poskytovateľa komunikačných služieb) si vyžaduje podstatne väčšie hardvérové nároky (viď odôvodnenie v bakalárskej práci).

Požiadavky na programové prostriedky

• ľubovoľný operačný systém s podporou Java Virtual Machine (JVM) (Windows XP/Server 2003/Vista, Linux alebo Solaris)
• Java Runtime Environment (JRE) verzie 1.6.0 a vyššej
• knižnica log4j-1.2.9.jar alebo vyššej (umožňuje zobrazenie log výstupov)

Závislosti aplikačného rozhrania

Aplikačné rozhranie umožňuje zrýchlené vyhodnocovanie dát sieťovej prevádzky, a preto bude implementáciou najvyššej vrstvy architektúry BasicMeter. Z toho vyplývajú jeho závislosti na moduloch, ktoré pracujú na prvej a druhej vrstvy spomínanej architektúry. Tieto moduly predstavujú:

• Kolektor verzie 3.1 (JXColl 3.1)
• Exportér (my\_beem)

Vlastná inštalácia

Aplikačné rozhranie si nevyžaduje inštaláciu ani preklad. Slúži na preportovanie protokolu ACP do aplikácií, ktorých funkčnosť je závislé na reálno-časových údajov. Z toho dôvodu jej samostatné použitie a spustenie je nemožné. Svoj účel spĺňa až v spojení výslednou aplikáciu, v ktorej budú použite funkcie poskytované ACPapim. Sprístupnenie funkcií aplikačného rozhrania je možné nakopírovaním súborov ACPapi.jar a log4j-1.2.9.jar dodávané na inštalačnom médiu na pevný disk (najlepšie do adresára aplikácie, v ktorej bude implementované) a pri preklade aplikácie následným nastavením parametrov classpath na tieto knižnice.

Použitie aplikačného rozhrania

Po nastavení referencií na knižnicu ACPapi a importovaní tried aplikačného rozhrania, jeho použitie spočíva vo volaní metód, ktoré sprostredkuje.

Popis dialógu s používateľom

Dialóg s používateľom závisí na návrhu a implementačných detailoch aplikácie v ktorej aplikačné rozhranie bude použité. Z toho dôvodu spôsob a forma dialógu sa prenechá na vývojárov alebo systémových programátorov spomínaných aplikácií. Aplikačné rozhranie je však možné použiť aj v konzolových, aj vo webových aplikácií, a zároveň v aplikáciach s grafickým rozhraním.

Popis správ pre systémového programátora

Počas behu aplikačného rozhrania sa vypisujú rôzne hlásenia od chybových až po informačné. Ich typ a popis je uvedený v nasledujúcej tabuľke. Každá úroveň zahŕňa v sebe aj úrovne na nižšom stupni.

Typ hlásenia	Popis
DEBUG	zobrazujú sa kompletné výpisy celého diania v programe
INFO	program informuje o svojej činnosti a akcii, INFO ktorú práve vykonáva
WARN	vypíšu sa informácie o upozorneniach programu na možné chyby alebo zlú interpretáciu vstupných dát
ERROR	sú vypísané hlásenia chýb majúcich vplyv na dáta
FATAL	hlásenia, ktoré sú pre beh programu smrteľné a zvyčajne znamenajú nezotaviteľnú chybu programu

Chybové hlásenia

Počas používania aplikačného rozhrania môže dojsť k neočakávaným chybám, ktoré sú uvedené nasledujúcej tabuľke:

Chybové hlásenie	Situácia	Riešenie
Wrong login or password. Authentication failed. Unknown message received.	Nepodarilo sa pripojiť na Kolektor.	Overiť autentifikačné údaje, a parametre pripojenia na Kolektor.
Not connected to collector.	Počas posielania riadiacich správ sa spojenie s Kolektorom nenašlo	Pravdepodobne niektorá strana prerušila spojenie. Treba sa znova pripojiť na Kolektor.
Not connected to collector.	Počas posielania riadiacich správ sa spojenie s Kolektorom nenašlo	Pravdepodobne niektorá strana prerušila spojenie. Treba sa znova pripojiť na Kolektor.
This message was not expected. Unknown reply message received.	Chybové hlásenia ktoré sa môžu vyskytnúť pri čítaní odpovedí na riadiace správy	Znovu poslať žiadosti prostredníctvom riadiacich správ.
Invalid source/destination IP address.	Nesprávny formát zdrojovej/cieľovej IP adresy.	Adresa musí byť zadaná v tvare A.B.C.D \ n. Parameter n nie je povinný.
Invalid port number. Invalid protocol number.	Nesprávny formát zápisu zdrojových/cieľových portov alebo protokolu.	Jednotlivé hodnoty musia byť oddelené čiarkami, hranice intervalov pomlčkou.
Invalid port range. Invalid protocol range.	Nesprávny formát zápisu intervalu zdrojových/cieľových portov alebo protokolu.	Jednotlivé hodnoty musia byť oddelené čiarkami, hranice intervalov pomlčkou.
	Upozornenia
Cannot send unpause while transfer is not paused... Cannot send transfer type while transfer is paused... Template rejected! Filter rejected! Pause rejected! Unpause rejected! Unknown Transfer Type!	V prípade odmietnutí žiadostí sa objavujú tieto upozornenia.	Overiť správnosť a včasnosť žiadostí a znovu poslať.

Príklad použitia

V príklade použitia bude uvedený spôsob nadviazania spojenia a prijímanie údajov prostredníctvom metód aplikačného rozhrania. V príklade nie je uvedené zachytenie výnimiek.

Importovanie potrebných balíkov z aplikačného rozhrania:

import sk.tuke.cnl.bm.Filter;
import sk.tuke.cnl.bm.InvalidFilterRuleException;
import sk.tuke.cnl.bm.ACPapi.ACP;
import sk.tuke.cnl.bm.ACPapi.ACPException;
import sk.tuke.cnl.bm.ACPIPFIXTemplate;
import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Logger; 

Vytvorenie objektov, potrebných pre prácu s metódami aplikačného rozhrania:

// nastavenie šablóny, posielajú sa iba ich identifikátory
int[] fields = {ACPIPFIXTemplate.sourceIPv4Address, ACPIPFIXTemplate.destinationIPv4Address};
//vytvorenie objektu Filter
Filter filter = new Filter();
//nastavenie filtračných kritérií
filter.ACPCreateFilter("127.0.0.1","192.168.1.1", "192.168.1.2", "2345", "8080", "80");
//vytvorenie objektu ACP, ktorým sprístupníme jeho metódy
ACP acp = new ACP();
//nadviazanie spojenia s Kolektorom
acp.connectToCollector("127.0.0.1", 2138, "bm", "bm");
//poslanie šablóny
acp.sendTemplate(fields);
//poslanie filtračných kritérií
acp.sendFilter(filter.createSimpleFilter());
//nastavenie typu prenosu na -> po jednom
acp.sendTransferType(2);

Prihlasovacie údaje na Kolektor závisia od nastaveniach v configuračnom súboru, ktorý je s nim podávaní. Jeho štandardné nastavenia sú:

• IP adresa alebo host, kde je Kolektor spustený
• číslo portu - 2138
• prihlasovacie meno - bm
• heslo - bm

Každá z týchto hodnôt je ľubovolne nastaviteľná, o ktorom sa čítateľ može dozvedieť viac v príručkach patriace k programu JXColl, ktoré sú súčasťami bakalárskej práce.

Prijímanie údajov:

Nasledujúci úsek zdrojového kódu slúži ako návrhový vzor pre získavanie dát prostredníctvom protokolu ACP.

int temp = 0; // premenná na kontrolu počtu zvyšných hodnôt aktuálneho paketu
int respondMessageType;    // premenná pre id prichádzajúcej správy
log.info("Starting to receive data.");
while (!acp.isFinished()) {   // začiatok cyklu, kontrola stavu
    if (!acp.isPaused() || acp.getIsReceiving() == true) {//kontrola pozastavenie, 
                  //prijatia každej hodnoty z aktuálneho paketu
        respondMessageType = acp.getDatInStr().readInt(); //načítanie prijatej správy
        log.debug("Received Message type:" + respondMessageType);
        switch (respondMessageType) {
             case COL_DATA_MSG:      // správa s id 0 / nasledovať bude údaj(e)
                if (acp.getTransferType() == 1) { // typu dátového prenosu po n-ticiach
               acp.isReceiving(true);// zabezpečenie prijatia každej hodnoty z aktuálneho paketu
                    for (int k = 0; k < acp.getFieldsToReadACP().length; k++) { 
                        byte[] buff = new byte[60];
                        int c = acp.getDatInStr().read(buff); // načítanie dát
log.debug(ACPIPFIXTemplate.getnamebyID(acp.getFieldsToReadACP()[k])+":"+new String(buff,0,c));
                        acp.getDatOutStr().writeInt(5);        //potvrdenie prijatia dát
                    }
                    acp.isReceiving(false);
                }  else if (acp.getTransferType() == 2) { // typu dátového prenosu po jednom
                   temp++;
                acp.isReceiving(true);//zabezpečenie prijatia každej hodnoty z aktuálneho paketu
                    byte[] buff = new byte[60];
                    int c = acp.getDatInStr().read(buff); // načítanie dát
                    log.debug("Data received : " + new String(buff, 0, c));
                    acp.getDatOutStr().writeInt(5); //potvrdenie prijatia dát
                    if (temp == acp.getFieldsToReadACP().length) { // kontrola počtu zvyšných 
                           //hodnôt aktuálneho paketu
                        temp=0;
                        acp.isReceiving(false);
                    }
                }
                break;
            case COL_ANSWER_MSG:   // správa s id 1 / nasledovať bude údaj(e)
                acp.readCollectorAnswers(); //spracovanie prijatých odpovedí na riadiace správy
                break;
            default:         //neočakávaná udalosť
           throw new ACPException("Unknown message type received (" + respondMessageType + ").");
        } //switch
    } else {
        log.info("Paused ... sleeping X)");    // stav pozastavenia prenosu
        sleep(1000);
    } //if-else
} //while

-- Main.adrian_pekar - 19 May 2009