ITI0011:Säuts lisaülesanne

See leht kirjeldab koduse ülesande ITI0011:Säuts lisaülesannet.

Kirjeldus

Lisaülesande eesmärk on võimaldada teie koodi automaatselt testida. Kui igaüks kirjutab funktsioonide nimed erinevalt, tuleb neid ka käsitsi testida. Seepärast oleme loonud n-ö malli, mille järgi kodust ülesannet luues on meil võimalik teie koodi automaatselt testida.

Ülesande sooritamine annab 1 punkti. See võib tunduda vähe. Samas, kui te algusest peale kasutate seda malli, siis mingit olulist lisatööd tegema ei pea. Kui te aga olete juba ülejäänud ülesande ära lahendanud, siis selle lisaosa "juurde tegemine" võib olla päris ajakulukas.

Lae alla Meedia:TwitterInterfaces_v1.zip, mis sisaldab interface'e, mida peate implementeerima oma koodiga. Lisaülesande lahendamine eeldab mõningaid OOP teadmisi (mida me tegelikult kõiki ka tunnis käsitleme).

Järgnevalt iga interface'i kohta väike kirjeldus.

IAction

Üldine tegevuse või korralduse interface. Kõik käsud peaksid seda implementeerima.

ICache

Puhvri funktsionaalsus. Selles sisaldub üks meetod, mis etteantud asukoha nimetuse järgi tagastab ITwitterQuery objekti. Seda peab implementeerima juhul, kui realiseerite puhverdamise lisaosa.

IFilterAction

Sortimise ja otsimise tegevus. Koondab kokku vajalikud andmed nii sortimiseks kui otsimiseks.

ILocationSearch

Asukoha otsingu funktsionaalsus (OpenStreetMap API või Google Maps API vms). Sisaldab ühte meetodit, kuhu antakse ette asukoha nimi ja vastuseks tagastatakse ITwitterQuery.

IQueryAction

Otsingu korraldus, hoiab vajalikke andmeid, mida saab kasutada otsingu tegemiseks.

ITweet

Andmeobjekt iga tweet'i jaoks. Twitteri API-st tehtav päring tagastab nimekirja nendest objektidest.

ITwitterApplication

Programmi põhiline funktsionaalsus on kirjeldatud selles interface'is.

Funktsioonide kirjeldused ja kuidas neid kasutada:

	/**
	 * Given a command as a String (in interactive mode), 
	 * this method should parse the input and return
	 * a list of IAction instances.
	 * Usually one command should create one action, this 
	 * method gives the opportunity to have combined actions
	 * for one command line ("query tallinn search kala").
	 * If you don't use combined actions, just return a list
	 * with one element in it - the IAction instance to be 
	 * executed. 
	 * @param action Command string from interactive mode
	 * @return List of actions to be executed
	 */
	public List<IAction> getActionsFromInput(String action);

Funktsioon võtab ette kasutaja poolt interaktiivses keskkonnas saadud käsu (nt "query Tallinn sort date").
Tagastab listi IAction tüüpi objektidest (listis võib olla ka üks element - "query tallinn" näiteks).


	
	/**
	 * Given command line arguments this method parses
	 * the arguments and returns a list of IAction instances.
	 * As the command line can accept several different actions
	 * (for example query, sort and search), this method
	 * return a list of all the actions.
	 * @param args Command line arguments (from main method)
	 * @return List of actions to be executed
	 */
	public List<IAction> getActionsFromArguments(String[] args);

Funktsioon võtab ette käsurealt saadud argumendid (samad, mis main-meetodisse lähevad).
Tagastab samuti listi IAction tüüpi objektidest.

	
	/**
	 * Given an instance of IAction, it will be executed.
	 * @param action
	 */
	public void executeAction(IAction action);

Käivitab ühe konkreetse IAction tüüpi korralduse. 
Peate jälgima, mis tüüpi laiendus see IAction'ist on ja vastavalt tegevusi tegema.

	
	/**
	 * Executes all the actions given as a list.
	 * The default implementation just iterates over
	 * all the actions and calls executeAction.
	 * @param actions A list of actions
	 */
	default public void executeActions(List<IAction> actions) {
		for (IAction action : actions) {
			executeAction(action);
		}
	}

Etteantud IAction tüüpi elementidega listist pannakse kõik tegevused käima
(ehk kutsutakse välja executeAction meetod).
Vaikimisi implementatsioon on kaasa pandud - seda ei pea üle kirjutama. 
Kui tekib vajadus, võite üle kirjutada.

	
	/**
	 * Executes a location search using location search set with
	 * setLocationSearch().
	 * Returns a query object which holds all the values for Twitter search.
	 * Note that this method has a default implementation which
	 * just executes a method from local location search and 
	 * returns its return value.
	 * Use this default implementation if you don't have caching implemented.
	 * If you need caching, you need to override this method.
	 * @param location The location which is to be searched for
	 * @return Query object which holds all the necessary information
	 * about Twitter query
	 * @see ITwitterApplication#setLocationSearch(ILocationSearch)
	 */
	default public ITwitterQuery getQueryFromLocation(String location) {
		ILocationSearch locationSearch = getLocationSearch();
		return locationSearch.getQueryFromLocation(location);
	}
	
Etteantud asukoha nimetusele koostab twitteri päringu.
See funktsioon peab kasutama ILocationSearch'i implementatsiooni.
ILocationSearch objekti instants peab olema määratud setLocationSearch() meetodiga.
Default implementatsioon ei võimalda puhverdamist, kui tahate puhverdamist, peate
meetodi üle kirjutama.



	
	/**
	 * Executes a search of tweets on TwitterSearch object which
	 * is stored via setTwitterSearch(). 
	 * Returns a list of received tweets. 
	 * @param query Query object which holds all the necessary values
	 * @return List of ITweet objects received from Twitter search.
	 * <code>null</code> if nothing received.
	 * @see ITwitterApplication#setTwitterSearch(ITwitterSearch)
	 */
	default public List<? extends ITweet> getTweets(ITwitterQuery query) {
		ITwitterSearch twitterSearch = getTwitterSearch();
		return twitterSearch.getTweets(query);
	}

Funktsioon saab ette ITwitterQuery objekti, milles on vajalikud parameetrid get-meetoditega kättesaadavad.
Päringu objekt saadetakse edasi ITwitterSearch implementatsioonile, mille instants saadakse getTwitterSearch()
kaudu. Üldiselt seda meetodit pole teil vaja üle kirjutada.
	

	/**
	 * Stores location search object which will
	 * be used to make queries to location search API.
	 * @param locationSearch Implementation of ILocationSearch, which
	 * can find information about location (city, country etc.).
	 */
	public void setLocationSearch(ILocationSearch locationSearch);

Selle meetodiga lisate oma implementatsiooni asukoha otsingu objektist.
	
	/**
	 * Returns currently stored location search object.
	 * @return Implementation of ILocationSeach
	 * which will be used for location search.
	 */
	public ILocationSearch getLocationSearch();

See meetod tagastab asukoha otsingu objekti.
	
	/**
	 * Stores Twitter search object which will be used
	 * to query tweets from Twitter API.
	 * @param twitterSearch Implementation of ITwitterSearch
	 */
	public void setTwitterSearch(ITwitterSearch twitterSearch);
	
	/**
	 * Returns currently stored Twitter search object.
	 * @return Implementation of ITwitterSearch
	 * which will be used for queries.
	 */
	public ITwitterSearch getTwitterSearch();

Kaks eelmist funktsiooni on ITwitterSearch objekti get ja set meetodid.

	/**
	 * Stores cache object which will be used
	 * to cache locations in the file.
	 * @param cache Implementation of ICache
	 */
	public void setCache(ICache cache);
	
	/**
	 * Returns currently stored cache object.
	 * @return Implementation of ICache
	 * which will be used for location caching.
	 */
	
	public ICache getCache();

Eelmised kaks on ICache objekti get ja set meetodid.
	
	/**
	 * Stores the latest state of tweets list.
	 * You should store your tweets using this
	 * method after querying, sorting, searching.
	 * @param tweets A list of tweets
	 */
	public void setTweets(List<? extends ITweet> tweets);
	
	/**
	 * Get the latest state of tweets list.
	 * This method should be used for printing
	 * and when applying sorting or searching.
	 * @return A list of tweets
	 */
	public List<? extends ITweet> getTweets();

Get ja set meetodid säutsude nimekirja jaoks.

ITwitterQuery

Andmeobjekt, mis hoiab Twitteri päringu jaoks vajalikke andmeid.

ITwitterSearch

Twitteri API-ga suhtlev objekt peab seda interface'i implementeerima. Sisaldab vaid ühte meetodit, mis etteantud ITwitterQuery tüüpi objekti korral tagastab nimekirja säutsudest.

Muu info

Programmi ülesehitus peaks välja nägema selline:

• Programm parsib kasutaja sisendi (kas käsurealt või interaktiivses keskkonnas) ja koostab IAction tüüpi objektid, mis pannakse listi.
• Saadud käskude listi käsud pannakse ükshaaval käima. Selleks saab listi ette anda ITwitterApplication.executeActions(..), mis on ka default implementatsiooniga ette antud ITwitterApplication interface'is. Kui vaja, võite selle meetodi üle kirjutada.
• Päringu käsu puhul otsitakse üles koordinaadid ja tehakse Twitteri API-sse päring:
  • Asukoht saadetakse ITwitterApplication.getQueryFromLocation(..), mis etteantud asukoha puhul teeb päringu OpenStreetMap API (või mõne alternatiivse) pihta ja tagastab ITwitterQuery tüüpi andmeobjekti vajalike väärtustega (koordinaadid, raadius jms).
  • Kui implementeeritud on ka puhverdamine, siis esimese sammu puhul kontrollitakse eelnevalt seda, kas nimetatud asukoht on puhvris olemas.
  • Saadud ITwitterQuery saadetakse ITwitterApplication.getTweets(..) meetodisse, mis tagastab nimekirja ITweet objektidest.
  • Nii asukoha otsingu kui ka Twitter API funktsionaalsust realiseerivad objektid (vastavalt ILocationSearch ja ITwitterSearch tüüpi) peavad olema instantsidena ITwitterApplication küljes - selleks ka vastavad set/get meetodid.
  • Saadud säutsude nimekiri salvestatakse mällu, et hiljem sellega operatsioone teostada.