handlerthread and intentservice post added

Author: maciej-nowak

_drafts/2019-06-24-handlerthread.md

@@ -0,0 +1,205 @@
+---
+layout: post
+title: "HandlerThread"
+date: 2019-06-24
+categories: ["Background"]
+image: background/handlerthread
+github: background/tree/master/handlerthread
+description: "Background threading"
+keywords: "thread, handler, handlerthread, looper, threadpool, executor, runnable, callable, future, async, task, background, threading, android, programowanie, programming"
+---
+
+## Thread
+Klasa `Thread` w `Java` reprezentuje wątek wykonania programu i jest podstawą wielu implementacji mechanizmów wielowątkowości. Pozwala na wykonanie pracy na innym wątku. W czystej implementacji bez wsparcia innych klas może służyć do wykonywania długich zadań bez komunikacji z wątkiem głównym. Wątek działa niezależnie od cyklu zycia aplikacji, dlatego potrafia przetrwać zmianę konfiguracji czy wyjście z aplikacji (trafia do póli wątków). Zatrzymanie działania następuje automatycznie po zakończeniu pracy lub w sposób manualny (metodą `interrupt`). Może być tylko raz wykonany zatem każde uruchomienie oczekiwanej pracy wymaga nowej instancji co sprawia, że nie nadaje sie do ponownego użytku. Komunikacja z wątkiem głównym może przebiegać przy użyciu klasy `Handler`.
+
+{% highlight kotlin %}
+class ThreadActivity : AppCompatActivity() {
+
+    val runnable = Runnable {
+        //some background job
+        runOnUiThread { 
+            //UI job if needed
+        }
+    }
+    val thread = Thread(runnable) //pass runnable or create anonymous object
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_thread)
+
+        button.setOnClickListener {
+            //do not allow start thread if is started
+            if(thread.state == Thread.State.NEW)
+                thread.start()
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        if(thread.state != Thread.State.TERMINATED)
+            thread.interrupt() //stop the thread if needed
+    }
+}
+{% endhighlight %}
+
+## Looper
+Mówiąc o wątkach w Android nie sposób nie wspomnieć o klasie `Looper`, która używana jest do uruchamiania pętli wiadomości dla wątku. Wspiera wykonanie pracy wątku przez dostarczanie wybranych wiadomości i zadań z kolejki do odpowiednich obiektów klasy `Handler`. Każdy wątek `Thread` może mieć jedną uniknalną instancje `Looper`.
+
+## Handler
+`Handler` umożliwia komunikacje między wątkami poprzez wykorzystanie kanału wiadomości. Jest pośrednio powiązany z wątkiem `Thread` poprzez bezpośrednie przekazanie obiektu `Looper` danego wątku w konstruktorze (domyślnie jest to `Looper` wątku w którym `Handler` jest tworzony). Działa więc na wątku, który jest właścicielem dostarczonej instancji `Looper`. Wiadomość `Message` może być wysyłana z dowolnego miejsca przez `sendMessage` oraz zostać odebrana przez `handleMessage` na wątku obiektu `Handler`. Natomiast zadanie `Runnable` wywoływane jest metodą post, a jego wykonanie odbywa się na wątku obiektu `Handler`.
+
+{% highlight kotlin %}
+class HandlerActivity : AppCompatActivity() {
+
+    val START = 1
+    val FINISH = 2
+
+    val runnable = Runnable {
+        //some background job
+        handler.sendMessage(createMessage(FINISH, "result")) //send message to handle action
+        handler.post { 
+            //do action on UI without message communication
+        }
+    }
+
+    val thread: Thread = Thread(runnable)
+
+    val handler = object: Handler(Looper.getMainLooper()) { //pass Looper of thread owner
+        override fun handleMessage(msg: Message?) {
+            super.handleMessage(msg)
+            if(msg?.what == START && thread.state == Thread.State.NEW) {
+                thread.start()
+            }
+            else if(msg?.what == FINISH) {
+                //some action with msj.obj result
+            }
+        }
+    }
+
+    fun createMessage(what : Int, obj : Any) : Message {
+        val message = Message()
+        message.what = what
+        message.obj = obj
+        return message
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_handler)
+
+        button.setOnClickListener {
+            //instead of direct thread.start() it can be done by sending message
+            handler.sendEmptyMessage(START)
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        handler.removeCallbacksAndMessages(null) //remove pending work from MessageQueue
+        thread.interrupt()
+    }	
+}
+{% endhighlight %}
+
+## HandlerThread
+`HandlerThread` jest rozbudowaną klasą `Thread`, która posiada własną instancję `Looper` i `Handler` dzięki czemu potrafi kolejkować zadania i może być użyty wielokrotnie. Zadania wykonywane są synchronicznie w sposób sekwencyjny. Obiekt `HandlerThread` podobnie jak Thread jest aktywny dopóki nie zostanie zniszczony automatycznie przez system lub ręcznie.
+
+{% highlight kotlin %}
+class HandlerThreadActivity : AppCompatActivity() {
+
+    //work to do by requestHandler
+    val runnable = Runnable {
+        //some background job
+        responseHandler.sendMessage(Message()) //send message or post the job
+        responseHandler.post { 
+            //some UI action
+        }
+    }
+
+    //handler on the main thread, override handleMessage if needed
+    val responseHandler = object: Handler(Looper.getMainLooper()) {
+        override fun handleMessage(msg: Message?) {
+            super.handleMessage(msg)
+            //some action on UI
+        }
+    }
+
+    //handler on the background thread of handlerThread object
+    lateinit var requestHandler: Handler
+
+    //instead of Thread use reusable HandlerThread
+    //this can be also done by extend HandlerThread class and putting there Handler object
+    val handlerThread = HandlerThread("HandlerThread")
+    
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_handler_thread)
+
+        handlerThread.start() //start the thread
+        requestHandler = Handler(handlerThread.looper) //now Looper of handlerThread can be passed
+
+        button.setOnClickListener {
+            requestHandler.post(runnable) //post the job to MessageQueue
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        //remove tasks and messages from handlers
+        requestHandler.removeCallbacksAndMessages(null)
+        responseHandler.removeCallbacksAndMessages(null)
+        handlerThread.quitSafely() //quit HandlerThread's Looper
+        handlerThread.interrupt() //stop current job
+    }
+}
+{% endhighlight %}
+
+## Pula wątków
+Pula wątków (`ThreadPoolExecutor`) jest pojedynczą kolejką typu `FIFO` składającą się z grupy wątków roboczych, które w momencie osiągnięcia stanu dostępności pobierają zadanie z kolejki. Umożliwia asynchroniczne wykonanie zadań przy zachowaniu optymalnej strategii przetwarzania wielowątkowoego, dostarcza mechanizm zarządzania wątkami (dodawanie, anulowanie, priorytety) oraz prostą statystykę. Pula wątków może być użyta przez jedną z implementacji interfejsu `Executor`, `Callable` czy `Future`. Przeważnie instancje uzyskuje się przy pomocy metody wytwórczej z klasy `Executors` oferującej kilka rodzajów typu puli watków.
+
+{% highlight kotlin %}
+class ThreadPoolActivity : AppCompatActivity() {
+
+    //this ExecutorService is wrapped ThreadPoolExecutor (this class extends ExecutorService)
+    //equivalent of ThreadPoolExecutor with min and max only 1 thread in pool and LinkedBlockingQueue
+    val executor : ExecutorService = Executors.newSingleThreadExecutor()
+
+    val runnable = Runnable {
+        //some background job
+        uiHandler.post {
+            //some UI job
+        }
+    }
+
+    val callable = Callable {
+        //some background job and return result
+        return@Callable "result"
+    }
+
+    val uiHandler = Handler()
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_thread_pool)
+
+        button1.setOnClickListener {
+            //use executor with Runnable        
+            executor.execute(runnable)
+        }
+
+        button2.setOnClickListener {
+            //use executor with Callable        
+            val future : Future<String> = executor.submit(callable)
+            val result = future.get()
+            //this can be canceled by run future.cancel()
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        //remove tasks and messages from handlers
+        uiHandler.removeCallbacksAndMessages(null)
+        executor.shutdownNow() //kill all threads
+    }
+}
+{% endhighlight %}

_drafts/2019-06-24-asynctask.md _drafts/2019-07-01-asynctask.md_drafts/2019-06-24-asynctask.md renamed to _drafts/2019-07-01-asynctask.md

@@ -1,7 +1,7 @@
 ---
 layout: post
 title: "AsyncTask"
-date: 2019-06-24
+date: 2019-07-01
 categories: ["Background"]
 image: background/asynctask
 github: background/tree/master/asynctask

_drafts/2019-07-08-intentservice.md

@@ -0,0 +1,140 @@
+---
+layout: post
+title: "IntentService"
+date: 2019-07-08
+categories: ["Background"]
+image: background/intentservice
+github: background/tree/master/intentservice
+description: "Background threading"
+keywords: "intentservice, jobintentservice, broadcastreceiver, async, task, background, onhandleintent, threading, android, programowanie, programming"
+---
+
+## Wstęp
+`IntentService` jest rozszerzeniem klasy `Service` o obsługę zadań przetwarzanych na w tle na dedykowanym wątku roboczym przy pomocy klasy Handler. Umożliwia wykonanie pracy w sposób asynchroniczny niezależnie od wątku głównego, jednakże obsługuje tylko jedno zadanie w danej chwili. Wysyłane żądania w postaci obiektu `Intent` zostają natychmiast obsłużone lub trafiają do kolejki oczekujących. Gdy cała kolejka zadań zostanie zrealizowana wówczas usługa automatycznie kończy pracę. Większość zdarzeń cyklu życia interfejsu użytkownika nie ma wpływu na działanie `IntentService` (w przeciwieństwie do `AsyncTask`). Przeznaczony jest przede wszystkim do prostych operacji w tle, które niekoniecznie wymagają reakcji interfejsu użytkownika na otrzymany rezultat.
+
+## Implementacja
+Aby stworzyć komponent `IntentService` należy zdefiniować klasę rozszerzającą klasę `IntentService`, nadpisać metodę `onHandleIntent` odpowiedzialną za przechwytywanie żądań i podobnie jak przy klasycznej usłudze (`Service`) dodać do pliku manifestu (`AndroidManifest`).
+
+{% highlight kotlin %}
+class CustomIntentService : IntentService("name") {
+
+    override fun onHandleIntent(intent: Intent?) {
+        //retrieve data
+        val action = intent?.action
+        val data = intent?.dataString
+        //do some work based on action
+    }
+
+    //avoid to override Service's callback like onStartCommand
+    //they are automatically invoked by IntentService
+}
+
+class MainActivity : AppCompatActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_main)
+        button.setOnClickListener { startIntentService() }
+    }
+
+	//just call startService to run IntentService
+    private fun startIntentService() {
+        val intent = Intent(this, CustomIntentService::class.java)
+        intent.action = "action"
+        intent.putExtra("extra", "value")
+        startService(intent)
+    }
+}
+{% endhighlight %}
+
+## Komunikacja
+`IntentService` nie dostarcza mechanizmu odpowiedzi zwrotnej do klientów. W celu implementacji komunikacji do interfejsu użytkownika lub innych fragmentów kodu aplikacji można posłużyć się m.in. `BroadcastReceiver` lub szyną zdarzeń.
+
+{% highlight kotlin %}
+class IntentServiceCommunication : IntentService("name") {
+
+    override fun onHandleIntent(intent: Intent?) {
+        //retrieve data
+        val action = intent?.action
+        val data = intent?.getStringExtra("extra")
+        //do some work based on action
+
+        sendBroadcast()
+    }
+
+    private fun sendBroadcast() {
+        val broadcastIntent = Intent("FILTER_ACTION")
+        broadcastIntent.putExtra("message", "result")
+        sendBroadcast(broadcastIntent)
+        Log.d("IntentService", "sendBroadcast")
+    }
+}
+
+class MainActivity : AppCompatActivity() {
+
+    private val receiver = CustomBroadcastReceiver()
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_main)
+        button.setOnClickListener { startIntentService() }
+
+        registerReceiver(receiver, IntentFilter("FILTER_ACTION"))
+    }
+
+    override fun onDestroy() {
+        //if service is running and don't need anymore callback then stop IntentService
+        unregisterReceiver(receiver)
+        super.onDestroy()
+    }
+
+    fun startIntentService() {
+        val intent = Intent(this, CustomIntentService::class.java)
+        intent.action = "action"
+        intent.putExtra("extra", "value")
+        startService(intent)
+    }
+
+    //implement as nested class if only need to interact with this activity
+    class CustomBroadcastReceiver : BroadcastReceiver() {
+
+        override fun onReceive(context: Context?, intent: Intent?) {
+            val message = intent?.getStringExtra("message")
+            //do something like update UI
+        }
+    }
+}
+{% endhighlight %}
+
+## Ograniczenia
+Poza koniecznością zapewnienia mechanizmu odpowiedzi zwrotnej do klienta oraz ograniczeniem przepływu pracy do jednego wątku należy uwzględnić także restrykcje procesów w tle dla `Service` (w tym `IntentService`) w wyniku których usługa musi działać w trybie `foreground` (inaczej zostanie po pewnym czasie zatrzymana). Rozwiązaniem tego problemu może być użycie `JobIntentService` lub wystartowanie usługi w trybie foreground (`startForegroundService`) i wyświetlenie notyfikacji z poziomu usługi (`startForeground`).
+
+## JobIntentService
+`JobIntentService` w zależności od wersji systemu dobiera optymalną strategię wykonywania kolejki zadań w tle. W przypadku wersji systemu od `Android Oreo` zadania zostaną wykonane przy użyciu `JobScheduler`, natomiast dla starszych wersji usługa zostanie wywołana w standardowy sposób przy pomocy metody `startService`. Klasa rozszerzająca `JobIntentService` powinna nadpisać metodę `onHandleWork` w której będzie wykonywana praca (podobnie jak w `onHandleIntent` w `IntentService`). Klient dodaje zadanie do kolejki wywołując `enqueueWork`.
+
+{% highlight kotlin %}
+class CustomJobIntentService : JobIntentService() {
+
+    companion object {
+        const val ID = 100
+
+        //method for enqueuing work to this service, just call from client to start
+        fun enqueueWork(context : Context, work : Intent) {
+            enqueueWork(context, CustomJobIntentService::class.java, ID, work)
+        }
+    }
+
+    override fun onHandleWork(intent: Intent) {
+        //do some job here
+        //use BroadcastReceiver or something else to post the result
+    }
+}
+{% endhighlight %}
+
+{% highlight xml %}
+<!-- remember to add Service to AndroidManifest in the same way like base JobService 
+//with required BINB_JOB_SERVICE permission -->
+<service
+    android:name=".CustomJobIntentService"
+    android:permission="android.permission.BIND_JOB_SERVICE"/>
+{% endhighlight %}