ITI0011:Säuts (2014)

Tagasi ITI0011 lehele.

English version of this homework: ITI0011:Twitter homework.

Üldine

Tähtaeg: 21. või 23. oktoober (vastavalt rühma tunnile)
Enne seda nädalat esitamine annab +1 lisapunkti.

Üldised nõuded:

• Kood ei tohi käivitamisel ühegi olukorra puhul anda stacktrace errori (ehk siis te peaksite kõikvõimalikud exceptionid kinni püüdma ja olukordi võimaluse korral parandada).
• Kõik objektid, objekti muutujad ja meetodid peavad olema kommenteeritud javadoc konventsiooni alusel. Selle nõude eiramine võtab ühe punkti punktisummast maha.

Ülesande eesmärk on luua interaktiivne programm, millega saab hallata avalikke säutse (i.k. tweets)

Programmi funktsionaalsus:

• programmi käivitamisel on võimalik kogu funktsionaalsust juhtida käsurea parameetritega (nt. java Twitter -location Tallinn -c 40 -w tweets.txt)
• kui programm käivitatakse ilma käsurea parameetriteta, avaneb interaktiivne keskkond, kuhu saab käske kirjutada
• programmil peab olema loetav juhis (nii käsurealt käivitades kui ka interaktiivses keskkonnas)
• kasutaja saab sisestada asukoha nimetuse (võib olla linn, objekti nimi vms), programm leiab viimased avalikud säutsud, mis on selle objekti või linna läheduses tehtud
• programm võimaldab määrata, mitu säutsu tulemuses väljastatakse
• programm võimaldab tulemusi sorteerida ettemääratud parameetri järgi

Täpsemaid juhiseid vaadake altpoolt.

Lisaosa: testitav kood (1p)

Antud ülesanne ei ole väga rangelt kirjeldatud, mis jätab tudengitele vabaduse loovuse näitamiseks. Küll aga pärsib selline vabadus testimise võimalust. Siin pakutakse välja teenida täiendab lisapunkt (kokku siis võimalik saada 11 punkti, kui kõik lisad ära teete) juhul, kui te teete oma koodi testitavaks. Sellejaoks anname ette päris mitu interface'i, mida teie peate implementeerima oma programmis. Interface'id võimaldavad meil kirjeldada ära, millised meetodid milliste argumentidega teie koodis olema - seega, me saame neid välja kutsuda ja ka testida.

Tähelepanu Kui te olete oma koodi juba valmis teinud ja tahate seda lisaosa sooritada, võib see tähendada, et peate suurema osa koodist ringi kirjutama. Seega, kui seda lisaosa jahite, peaksite algusest peale oma koodi vastavalt üles ehitama. Kuna antud ülesande puhul on testitavuse võimaldamiseks vaja suhteliselt palju täiendavat tööd teha (mida te muidu tegema ei peaks), siis on ka selle eest lisapunkt pakutud.

Loe lähemalt siit: ITI0011:Säuts lisaülesanne

Põhiosa - 5p

Teie programm teeb päringu sotsiaalvõrgustiku Twitter avalike säutsude (tweet) seast. Päritakse viimased avalikud säutsud vastavalt etteantud kohanimele ja kuvatakse need kasutajale.

Funktsionaalsus:

• loetakse etteantud kohanimi (nt Tallinn)
• kohanime kohta päritakse tema geograafilised koordinaadid (latitude, longitude)
• saadud geograafilisi koordinaate kasutatakse, et arvutada välja säutsude kogumise keskpunkt ja otsitava ala raadius
• Twitteri API-sse saadetakse päring vastavalt määratud keskpunkti ja raadiusega
• Twitteri API vastusest loetakse välja vajalikud andmed ja kuvatakse ekraanile.
• programmile saab kohanime ette anda käsurealt

Kohanimele vastavad koordinaadid

Kasutame OpenStreetMap kommuuni tööriista Nominatim (Nominatim wiki leht). Te saadate sellele tööriistale päringu soovitud kohanimega ja vastusest loete välja kohanimele vastavad koordinaadid (latitude ja longitude) ning ümbritseva ala piirmised punktid (bounding box).

Näitepäring: http://nominatim.openstreetmap.org/search?q=Tallinn&format=xml

Sealt saate tulemuse (kompaktsuse mõttes on näidatud vaid olulisem osa tulemusest):

<searchresults timestamp="Sat, 13 Sep 14 21:47:21 +0000" 
attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright" 
querystring="Tallinn" polygon="false" 
exclude_place_ids="98174326,11438224,6000303521,6919504,6893196,86869124,15103978,5983246058" 
more_url="http://nominatim.openstreetmap.org/search?format=xml&
exclude_place_ids=98174326,11438224,6000303521,6919504,6893196,86869124,15103978,5983246058&accept-language=en-
US,en;q=0.5&q=Tallinn">
<place place_id="98174326" osm_type="relation" osm_id="2164745" place_rank="16" 
boundingbox="59.351806640625,59.5915794372559,24.5501689910889,24.9262847900391" lat="59.4372155" 
lon="24.7453688" display_name="Tallinn, Harju maakond, Estonia" class="place" type="city" 
importance="0.7819722223575" icon="http://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png"/>
...
</searchresults>

Tulemuseks saate mitu erinevat kohta, mille nimi on Tallinn (või nimes sisaldub selline sõna). Kõige esimene vaste meie programmi jaoks sobib. Seega loete välja esimese "place" elemendi. Kuna Twitteri päringu jaoks on meil vaja koordinaati ning raadiust (kui suure ala pealt tulemusi otsitakse), siis huvitavad meid atribuudid "lat" ja "lon" (latitude ja longitude), mis määravad ära keskpunkti, ning atribuut "boundingbox", mis näitab antud asukoha ümbritseva ala piirjooni. Antud näite näite puhul lat="59.4372155", lon="24.7453688", boundingbox="59.351806640625,59.5915794372559,24.5501689910889,24.9262847900391".

Twitteri päringus otsitav piirkond on märgitud keskpunkti ning raadiusega. Keskpunktiks võib kasutada otse eelnevalt saadud "lat" ja "lon" väärtusi. Raadiuse leidmiseks võib kasutada "boundingbox" väärtust. Kuna raadius peab olema esitatud näiteks kilomeetrites, siis tuleks boundingbox argumentide järgi leida mõistlik raadius. Tähelepanu, erinevas maakera piirkonnas on näiteks longitude 0.1 ühikuline erinevus oluliselt erineva pikkusega. Antud ülesande jaoks ei pea te arvutama väga täpse raadiuse, mis piiratud alasse sisse jääb. Piisab, kui te suurusjärgu panete paika. Siin ülesande kirjelduses konkreetset valemit või näidet toodud ei ole - selle võrra tulevad loodetavasti esitatud kodused ülesanded võimalikult erinevad. Väga täpseks ja põhjalikuks ei tasu ka minna - boonuspunkte selle arvutuse eest üldjuhul ei saa. Oluline on, et oluliselt erineva suurusega linnad annaksid erineva raadiuse (New York > > Tallinn > Haapsalu).

Seega teil on oluline, et oskate vajalikud andmed välja lugeda ning need teisendada keskpunktiks ja raadiuseks.

Märkus. Põhiosa lahendamiseks sobib ka see, kui kasutate mõnda muud API-t (näiteks Google Maps'i oma).

Twitteri API

Twitteri API (https://dev.twitter.com/docs/api/1.1) võimaldab programmiga teha automaatseid päringuid sotsiaalvõrgustiku Twitter andmetest. Antud ülesande lahendamiseks ei pea te olema aktiivne Twitteri kasutaja.

Twitteri API kasutamiseks on teil vajalik siiski luua konto ning selle alla App (application). Kui olete twitteri konto teinud ja sisse loginud, peaksite nägema oma rakendusi sellelt lehelt: https://apps.twitter.com/ (link on olemas ka dev.twitter.com veebilehe lõpus "TOOLS" nimekirja all). Seal looge oma app, kus võite veebileheks panna suvalise URL-i (kasvõi kursuse veebilehe).

Kui olete oma rakenduse loonud, näete seda oma applications nimekirjas. Kui avate loodud rakenduse, siis "API keys" tääbi alt avanevad rakenduse seaded. Sealt huvitavad meid "API key" ja "API secret". Neid kahte väärtust on vaja, et teha päringuid Twitter API-st.

Päring ise, mida peab kasutama, on kirjeldatud siin: https://dev.twitter.com/rest/public/search ja https://dev.twitter.com/rest/reference/get/search/tweets

Näiteks võiks päring olla selline: https://api.twitter.com/1.1/search/tweets.json?q=&geocode=59.437215524.7453688,1km&result_type=recent

Mainitud link brauseris ei peagi tulemust andma, kuna te pole eelnevalt sisse loginud. See annab Tallinnas säutse 1km raadiuses.

Natuke informatsiooni, kuidas rakendust vastu Twitteri API-t autentida: https://dev.twitter.com/oauth .

Selleks, et kogu protsess ei oleks liiga töömahukas ja keeruline, soovitame antud ülesande jaoks kasutada mõnda teeki (library), mis oskab autentimise ja ka pärimise teie eest ära teha. Üks selline, mille kohta on allpool ka paar koodinäidet, on siin: http://twitter4j.org/ . Kui tahate ja oskate, võite kasutada ka mõnda muud.

twitter4j puhul on teil vaja kätte saada järgmine fail: twitter4j-core-4.0.2.jar . Kui tõmbate alla zip-formaadis arhiivi, paikneb see fail kaustas "lib". Kirjutamise hetkel oli kasutusel versioon 4.0.2, see võib vabalt muutuda - vastavalt on siis ka failinimi erinev. Selle jar-faili peate oma Eclipse'i projekti lisama: project properties > java build path > libraries tääb > add external jars ... ning otsite üles nimetatud faili.

Konfigureerimise üks võimalus on selline:

		ConfigurationBuilder cb = new ConfigurationBuilder();
		cb.setDebugEnabled(true)
		.setApplicationOnlyAuthEnabled(true);
		cb.setOAuthConsumerKey(TWITTER_CUSTOMER_KEY)
		  .setOAuthConsumerSecret(TWITTER_CUSTOMER_SECRET);
		
		TwitterFactory tf = new TwitterFactory(cb.build());
		twitter4j.Twitter twitter = tf.getInstance();
		
		OAuth2Token token;
		try {
			token = twitter.getOAuth2Token();
		} catch (TwitterException e1) {
			// TODO Auto-generated catch block
			e1.printStackTrace();
		}

Üleval näites TWITTER_CUSTOMER_KEY ja TWITTER_CUSTOMER_SECRET on konstandid ja nende väärtused on võetud twitteri lehel loodud rakenduse lehelt (application key ja application secret vastavalt). Loomulikult võite seadistamise teha ka konfiguratsioonifailiga või muudmoodi (selle kohta leiate rohkem infot teegi kodulehelt).

Seda, kuidas nüüd teegiga vajalik päring teha, peate ise uurima. Aga selle kohta on veebilehel olemas ka paar näidet.

Kui teil on Twitteri konto olemas, saate olemasoleva konto alla luua rakenduse. Kuigi üldiselt on ülesande eesmärk pärida avalikke säutse, võite teha rakenduse, mis pärib teie kasutajaga seotud säutse (ehk siis nende omasid, keda jälgite ja/või kes on sõbrad). Jällegi, üldjuhul see lisapunkte ei anna. Tähelepanu, kui teete päringuid oma sõbrade kohta, on teil lisaks rakenduse võtmele lisada juurde ka teie enda võtmed. Selle kohta leiate näiteid siit: http://twitter4j.org/en/configuration.html . Kõik sealsed näited käivadki selle olukorra kohta, kus on vaja teha päringuid konkreetselt teie kasutaja alt. Kui te oma kasutaja infot ei lisa, saab teostada vaid avalikke päringuid.

Lisaosa: kohanimede puhverdamine (2p)

Selle lisaosa funktsionaalsus on:

• asukoha koordinaatide päringu tulemused salvestatakse faili, et järgmisel korral ei peaks neid uuesti küsima (kohalik cache)
• nimetatud faili saab lisada ise uusi asukohti (näiteks "kodu", "TTÜ" jne)

Puhverdamiseks kasuta faili "kohad.csv", mis peab olema sinu programmile kättesaadav (soovitavalt paikneb samas kataloogis käivitatava klassiga) ja peab koosnema CSV kujul ridadest:

   ametlik_nimi,latitude,longitude,raadius_km,alternatiivnenimi_1,..,alternatiivnenimi_N

või ridadest, kus koordinaadid ja raadius on puudu:

   ametlik_nimi,,,,alternatiivnenimi_1,...,alternatiivnenimi_N

kus

• ametlik_nimi on kohanimi, mida otsitakse API-st
• alternatiivnimi_1, ..., alternatiivnimi_N on nimed, mida kasutaja saab sisestada. Näiteks saab kasutaja siin määrata "kodu". Kui vastav päring tehakse, otsitakse tegelikult ametlik_nimi asukohta (või kasutatakse juba olemasoelvaid koordinaate ja raadiust, kui need on olemas)
• latitude, longitude ja raadius_km on standardse tähendusega. Need võivad puududa.

Sinu programm kasutab kohad.csv faili järgmiselt:

• Enne API poole pöördumist vaatab programm, kas vastav kohanimi on selles failis olemas
  • Kui jah, ja koordinaadid-raadius on antud, kasutab ta koordinaate ja raadiust Twitteri päringu tegemiseks. Asukoha päringut ei tehta
  • Kui jah, aga koordinaadid on puudu, siis
    • teeb uue asukoha API päring ametliku kohanime järgi, leiab koordinaadid ja arvutab raadiuse
    • kirjutab saadud koordinaadid ja raadiuse vastava rea juurde. Järgmisel korral sama päringu puhul pole vaja asukoha API-t enam kasutada.
  • Kui ei, siis tehakse uus päring ning puhverdatakse tulemused faili (kirjutatakse uus rida, kus on ametlik_nimi, koordinaadid ja raadius).

Näited:

1) kohad.csv:

   tallinn,59.4,24.5,10,kodu,ttü

Kui tehakse otsing "tallinn", siis kasutatakse koordinaate 59.4 ja 24.5, raadius = 10km. Sama juhtub, kui teha päring "ttü", "kodu". kohad.csv fail ei muutu.

2) kohad.csv:

   pärnu,,,,vanaema,suvila

Kui tehakse otsing "pärnu" või "vanaema" või "suvila", siis otsitakse asukoha API-ga üles "pärnu", loetakse välja koordinaadid ja arvutatakse välja raadius. Tulemuseks on sama rida failis:

   pärnu,58.3,24.5,5,vanaema,suvila

3) kohad.csv:

   tallinn,59.4,24.5,10,kodu,ttü

Kui tehakse otsing "pärnu", siis tehakse asukoha otsing "pärnu" ja salvestatakse koordinaadid ja raadius faili. Tulemuseks on fail:

   tallinn,59.4,24.5,10,kodu,ttü
   pärnu,58.3,24.5,5

See lisaosa täielikult realiseerituna annab 2 punkti.

Lisaosa: sorteerimine (1p)

Tweet'id väljastatakse sorteeritult vastavalt etteantud väljale. Sorteerida saab järgmiste väljade järgi: autor, postituse kuupäev, postitus (ehk siis tweet ise).

Sorteerimine peab toimima nii kasvavas kui kahanevad järjekorras.

Näiteks käivitatakse programm:

• java Twitter Tallinn -sort author
• java Twitter Tallinn -sort date
• java Twitter Tallinn -sort date desc
• java Twitter Tallinn -sort content

See lisaosa täielikult realiseerituna annab 1 punkti.

Lisaosa: filtreerimine (1p)

Lisaks kohanimele saab ette anda: otsingusõna ja väljastavate tweetide arvu. Tweetide arv tuleb kaasa anda päringu tegemisel. Otsingusõna tuleb rakendada aga saadud tulemuste peale.

Kui realiseeritud on nii tweetide arvu piiramine kui ka otsingusõna rakendamine saab 1 punkti.

Lisaosa: interaktiivne ja käsurealt juhtimine (1p)

Lisaosa mõte on võimaldada programmi käivitada nii käsurealt:

   java Twitter Tallinn -count 50 -sort date desc -search tere

kui ka luua interaktiivne keskkond, kus saab käske edasi anda. Interaktiivne keskkond tähendab seda, et programmi käivitamisel küsitakse kasutajalt sisendit ehk käsku. Käsk täidetakse ning seejärel saab kasutaja sisestada uue käsu (nagu command prompt või terminal). Näiteks:

   > setcount 50
   > query Tallinn
   > print
   > query Pärnu 10
   > sort date desc
   > print
   > search tere
   > print

Kui programm käivitatakse käsurea argumentidega (esimene näide), siis programm teeb vajalikud sammud ära ja lõpetab töö. Kui käsurealt argumente ei antud, käivitub interaktiivne keskkond.

Programm peab tundma järgmisi käske (interaktiivses keskkonnas peaks olema need käsud eraldi):

• päringu tegemine (näites "query"). Päringu tegemisel saab kaasa anda tweetide koguse (kui see lisaosa on tehtud; näites "query Pärnu 10"). Võib teha piirangu määramise ka eraldi (näites "setcount 50", see jääb siis kehtima järgmiste päringute puhul).
• Ainult interaktiivses: tulemuste printimine (näites "print"). Te võite tulemused printida ka kohe peale päringu tegemist. Aga muude operatsioonide puhul on mugav, kui print on eraldi. Käsurea käivitamise puhul prinditakse tulemused alati välja (peale muude operatsioonide tegemist).
• sorteerimine (näites "sort date desc"), kui vastav lisaosa on tehtud
• otsimine (näites "search tere"), kui vastav lisaosa on tehtud
• abi saamine (näiteks "help"). Kui sisestatakse vale argument (käsurealt käivitamisel) või käsk (interaktiivne käivitamine), siis peaks ka näitama abiteksti.

Selle lisaosa tegemisel on lisaks nõue see, et nii käsurealt saadud argumendid kui ka interaktiivselt edastatud käsud käivitatakse ühte moodi. Ehk siis mõlemal juhul töödeldakse nad samale kujule ja seejärel käivitatakse. Selle mõte on see, et teie programm oskab operereerida erinevate käskudega. See, kuidas programm need käsud kasutaja käest teada saab, pole käivitamise jaoks oluline. Kui te hiljem kunagi tahate lisada võimaluse käske saata üle veebi API, siis peate lisama lihtsalt käskude vastuvõtmise ja teisendamise ühtsele kujule (nagu ka käsurealt ja interaktiivsest keskkonnast) - ülejäänud juba töötab.

Kuigi see lisaosa tundub justkui väga mahukas 1 punkti kohta, siis tegelikult see väga keeruline pole. Niiehknaa on teil vaja realiseerida üks kahest: kas interaktiivne või käsurea variant. Vastasel korral te ei saa muid lisapunkte ka saada. Kui te kohe oma programmi loomise käigus arvestate võimalusega käivitada käske kahest erinvast kohast, siis hiljem mingeid täiendavaid arendusi teha pole vaja. Kui te olete teinud käsurealt käivitamise koos lisaülesannetega valmis ja hakkate seda lisaülesannet tegema, võib selle realiseerimine olla mõnevõrra keerulisem.

See lisaosa annab 1 punkti.