Programmare con le API Java

OrientDB è realizzato in Java, e di conseguenza sono disponibili API di buon livello per l'interfacciamento tramite questo linguaggio. Vi sono tre modelli di API da sfruttare, ognuno rappresentante una diversa "anima" del DBMS:

• Document API: sono le API più immediate da usare anche perchè coincidono con uno degli usi più comuni di un database NoSQL. Permettono di trasformare oggetti Java in documenti e salvarli all'interno di OrientDB;
• Object API: si basano sulle API a documenti e permettono di lavorare con dei veri e propri oggetti Java persistenti, sfruttando il meccanismo della reflection;
• Graph API: queste API permettono di lavorare su grafi, una delle strutture dati più duttile che esista. Tra l'altro, il loro uso si interseca con TinkerPOP

, progetto patrocinato dalla fondazione Apache.

Tale stratificazione delle funzionalità viene ben rappresentata dalla figura seguente:

La documentazione ufficiale suggerisce di utilizzare le API a grafo, in quanto sono in grado di coprire l'80% degli usi, relegando le pure API a documenti al restante 20% dei casi. Le Graph API sono effettivamente complete ma richiedono una certa confidenza con il tipo di struttura dati.

Gestione delle dipendenze

Il primo passo per poter lavorare con le API di Java è risolvere le dipendenze, ossia includere nel classpath del progetto le necessarie librerie .jar, reperibili in OrientDB. Il pacchetto necessario si chiama orientdb-core-*.jar, ed è sufficiente per l'uso a documenti.

Se si vuole passare al modello ad oggetti, si dovrà aggiungere anche il pacchetto orientdb-object-*.jar, mentre il set completo per programmare con le Graph API sarà costituito da orientdb-core-*.jar, blueprints-core-*.jar e orientdb-graphdb-*.jar con l'aggiunta di jna-*.jar, jna-platform-*.jar e concurrentlinkedhashmap-lru-*.jar.

Chiariamo infine che se non si ha interesse a connettersi ad un database locale ma si vuole praticare la via dell'accesso remoto, serviranno altri due .jar in tutti e tre i casi: orientdb-client-*.jar e orientdb-enterprise-*.jar.

Gli asterischi indicati rappresentano il numero di versione della libreria, che sarà differente a seconda della nostra installazione del DBMS.

Programmare con i grafi

Quello che segue è un esempio introduttivo all'uso delle API a grafo, che mostra i principali meccanismi di base: consisterà nella creazione di tre nodi - ognuno rappresentante una città - e la creazione di due archi che avranno come proprietà la distanza tra le due città collegate:

OrientGraphFactory factory = new OrientGraphFactory("plocal:C:/tempdb").setupPool(1,10);
		OrientGraph graph = factory.getTx();
		try {
			Vertex roma = graph.addVertex(null);
			roma.setProperty("nome", "Roma");
			Vertex torino = graph.addVertex(null);
			torino.setProperty("nome", "Torino");
			Vertex milano = graph.addVertex(null);
			milano.setProperty("nome", "Milano");
			Edge daRomaAtorino = graph.addEdge(null, roma, torino, "Roma-Torino");
			daRomaAtorino.setProperty("distanza", Integer.valueOf(689));
			Edge damilanoAtorino = graph.addEdge(null, milano, torino, "Milano-Torino");
			damilanoAtorino.setProperty("distanza", Integer.valueOf(141));
			for (Vertex v : graph.getVertices()) {
				String s=v.getProperty("nome");
			    System.out.println(s);
			}
			for (Edge e : graph.getEdges()) {
				Integer s=e.getProperty("distanza");
			    System.out.println(s);
			}
		} finally {
		   graph.shutdown();
		}
	}

Per prima cosa, è stato creato un grafo mediante il meccanismo della factory. Tale struttura dati deve essere basata su un database di cui forniremo l'URL che, come abbiamo già imparato, potrà indicare una risorsa locale (plocal:), remota (remote:) o in memoria (memory:). Il grafo ottenuto deve essere chiuso al termine delle operazioni tramite l'operazione di shutdown. Si ricordi che, vista la complessità che li caratterizza, i grafi vengono gestiti, di default, con transazioni, la cui chiusura avverrà allo shutdown o alla
prima invocazione del metodo commit.

Si creano poi tre vertici e due nodi. Per aggiungere delle proprietà si usa il metodo setProperty che avrà bisogno di soli due parametri: il nome della proprietà ed il suo valore. Da notare che la creazione di un Edge, in quanto collegamento tra nodi, richiede i riferimenti ai due vertici da congiungere. I due cicli for che troviamo alla fine mostrano come è possibile ottenere l'elenco degli archi e dei nodi e stamparne le proprietà in output.

Programmare a documenti

Le API a documento, seppur di natura diversa, seguiranno la sequenza di operazioni della precedente: apertura di un database, interazione con i dati e chiusura per la corretta gestione delle risorse con close().

Vediamo un esempio:

ODatabaseDocumentTx db = new ODatabaseDocumentTx("plocal:rubrica").open("admin", "admin");
       try {
            ODocument persona = new ODocument("Persone")
               .field("nome","Lorenzo")
               .field("cognome", "Rossi")
               .field("citta","Roma");
            persona.save();
       } finally {
            db.close();
       }

Anche questo esempio non ha bisogno di un server in esecuzione, in quanto ci connetteremo ad un database esistente. Qualora volessimo crearne direttamente uno in Java, non dovremo far altro che utilizzare il codice seguente:

ODatabaseDocumentTx db = new ODatabaseDocumentTx("plocal:rubrica").create();

Il nostro codice inserisce un record all'interno della classe Persona, non strutturata, composto da tre campi i cui valori saranno passati con il metodo field() in maniera simile ad una mappa. Per una corretta gestione dei dati, la connessione deve essere chiusa con l'invocazione di close() all'interno del blocco finally.

Si possono recuperare i record appartenenti ad una determinata classe o cluster tramite, rispettivamente, i metodi browseClass() e browseCluster(). Ad esempio, il seguente codice:

for (ODocument doc:db.browseClass("Persone"))
	           System.out.println(doc);

recupera i record della classe denominata Persone e stampa in output ogni documento. In questa maniera, i dati verrano visualizzati in un formato standard stile JSON, ma si potrà personalizzare il tutto estraendone i singoli campi.

Eseguire comandi

Quanto presentato è solo un'introduzione alle API disponibili, che può essere approfondita facendo riferimento alla documentazione ufficiale. È bene notare che il linguaggio SQL di OrientDB può essere impiegato sia sui grafi che sui documenti. In entrambi i casi, si tratterà essenzialmente di creare un oggetto "comando"
al quale verrà fornita l'istruzione SQL, e lo si potrà eseguire attraverso la connessione al database. Viene anche fornita la possibilità di svolgere i comandi in modalità asincrona per parallelizzare il flusso di esecuzione.