If you look at Compose it's weird. You have tons of functions that return nothing. Yet the Android documentation says:

Composable functions emit UI hierarchy.

What does this actually mean? Well, from a functional programming point of view your innocuous looking stateless composable functions create loads of side effects¹⁾. Among other things they create nodes.

Sometimes you might create Composables that create nodes yourself. But more often you will simply delegate to other Composables that then create the nodes.²⁾

So let's have a look at what nodes we have, where they are created and what purpose they fulfill:

• ComposeUiNode
• LayoutNode
• Modifier.Node
• SemanticsNode

ComposeUiNode

When you dig into the Layout composable you see that it calls ReusableComposeNode:³⁾:

@Composable
@UiComposable
inline fun Layout(modifier: Modifier = Modifier, measurePolicy: MeasurePolicy) {
    val compositeKeyHash = currentCompositeKeyHash
    val materialized = currentComposer.materialize(modifier)
    val localMap = currentComposer.currentCompositionLocalMap
    ReusableComposeNode<ComposeUiNode, Applier>(
        factory = ComposeUiNode.Constructor,
        update = {
            set(measurePolicy, SetMeasurePolicy)
            set(localMap, SetResolvedCompositionLocals)
            set(materialized, SetModifier)
            set(compositeKeyHash, SetCompositeKeyHash)
        },
    )
}

ReusableComposeNode is no node in itself. What you see in the code above is no constructor call. It's instead just a call to yet another Composable. An apparently innocuous bit is the factory argument in line eight - even though it is very important. Because that's the function that eventually will create a node. It will create a ComposeUiNode.

The ReusableComposeNode Composable is highly tied to the Compose runtime. That's the code that tells the composer that a new group of type GroupKind.ReusableNode should be started and then the code either creates a new node or reuses the existing one if we're recomposing. And finally it sets its content when the update function argument is used:

@Composable
inline fun <T : Any, reified E : Applier> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater.() -> Unit
) {
    if (currentComposer.applier !is E) invalidApplier()
    currentComposer.startReusableNode()
    if (currentComposer.inserting) {
        currentComposer.createNode(factory)
    } else {
        currentComposer.useNode()
    }
    Updater(currentComposer).update()
    currentComposer.endNode()
}

We see that the factory gets passed on to the createNode() call. This call schedules the node to be created when all insertions are processed. The compose runtime defers many things internally to allow for optimizations. Here we're not interested when this actually happens, suffice to say it will happen. And when it happens, the factory is going to be called.

Now let's look at the factory itself a bit closer: ComposeUiNode.Constructor seems to be the constructor of the ComposeUiNode. But that's once again not what it seems to be. Instead ComposeUiNode is an interface that in itself doesn't do anything. It's actually the base interface used by LayoutNode - and the reason for this interface and this constructor method is given in the comment above the interface declaration:

/** Interface extracted from LayoutNode to not mark the whole LayoutNode class as @PublishedApi. */
@PublishedApi
internal interface ComposeUiNode {
    // ...
    /** Object of pre-allocated lambdas used to make use with ComposeNode allocation-less. */
    companion object {
        val Constructor: () -> ComposeUiNode = LayoutNode.Constructor
        val VirtualConstructor: () -> ComposeUiNode = { LayoutNode(isVirtual = true) }
        // ...
    }
}

So ComposeUiNode is only an abstraction of LayoutNode.

LayoutNode

In the section above we have seen when a LayoutNode actually get's created. Basically whenever the Layout composable is called. The LayoutNode is the element in the tree that represents something on the screen. It needs to be measured, it might place children within its bounds and it might draw content.

Each LayoutNode knows of its children and of its parent. So LayoutNodes form a tree of nodes that represents the stuff that was emitted. To be clear: Compose creates a tree just like any other UI framework - but Google preferred to use some fancy naming for that. So whenever you hear/read about Composables emitting something, think about a LayoutNode getting created and inserted into the tree.

The LayoutNode class is actually pretty interesting and thus merits a blog post on it's own, where I will cover some aspects of it in more detail.

Two things are worth mentioning here:

• The Applier is the instance that calls the respective tree handling methods of LayoutNode.
• The LayoutNode holds a reference to an Owner.

I will cover both, the Applier as well as the Owner in separate blog posts since both are very important concepts when it comes to Compose.

The purpose of a LayoutNode

LayoutNodes form the UI tree and keep track of their parent node and child nodes. The management of the UI tree itself is done by the Applier, which I will cover in another post.

And - also very important to keep in mind - the LayoutNode gets stored in the SlotTable.⁴⁾ Thus when recomposing the runtime can reuse existing LayoutNodes in case it decides that no change is required for this part of the tree.

The LayoutNode also holds onto it's modifiers (see next section) and delegates to them to decide how much place is needed by this LayoutNode (measuring), where to place stuff on the screen (layout) and finally what to show on the screen (drawing).

There's more to it - but as I mentioned that's part of another post.

Modifier.Node

Modifiers are internally represented by Modifier.Node objects. According to the doc it is the "longer-lived object that is created for each Modifier.Element applied to a androidx.compose.ui.layout.Layout."

This "longer-lived" is interesting. Basically your Modifier.Node lives for as long as it belongs to the modifier chain of a LayoutNode. The LayoutNode holds onto an object of type NodeChain which keeps a list of modifiers internally and checks that, if this list is changed, the lifecycle methods of Modifier.Node - like onAttach() etc. - are called.

There are many existing subtypes of Modifier.Node - for example LayoutModifierNode (see below) or DrawModifierNode. The latter is responsible for actually drawing content on the screen, which I also plan to cover in a separate post.

Since LayoutNodes are part of the SlotTable the Modifier.Nodes that are attached to a LayoutNode's NodeChain object obviously are part of that.

A special subtype: LayoutModifierNode

LayoutModifierNodes are the nodes that actually measure since they are the nodes that affect the size and placement on screen. As the documentation states: "A Modifier.Node that changes how its wrapped content is measured and laid out.". So whenever the chain of Modifier.Nodes is traversed during measuring and laying out these nodes actually start the measuring.

Thus all modifiers that want to change the placement of their children or have any effect on the size of the overall Composable need to implement LayoutModifierNode. One example for doing that is the SizeNode which is the actual node used by modifiers like height(), width() or size().

SemanticsNode

When you want to pass some information to the accessibility services of the device, you use the semantics modifiers in Compose to tell the system which semantics properties to convey to the user.

But the accessibility services⁵⁾ do not know of Compose. On other platforms that's obvious but given that Compose is backwards compatible (and on top of that not part of the deliverables of the Android framework), that's true on Android as well.

For accessibility the aforementioned Owner comes again into place. It holds onto a SemanticsOwner which acts as a bridge to the semantics framework of the respective platform.

To do so, the SemanticsOwner holds onto a tree of SemanticNode objects to describe the contents of the screen to users of accessibility services. Another thing I intend to cover in more detail in the future.

So stay tuned for more insights into Compose inner workings. Happy coding!

The post The Different Node Types in Jetpack Compose appeared first on Grokking Android.

But then, it got me thinking: "Wait a moment! Why is this even necessary?"

Don't get me wrong, I really think this addition is necessary and it is a big improvement. But...

Well, to be honest, this and similar changes are only necessary because we developers are not careful enough. We kill precious bandwidth or - in this case battery life - by being overly generous with the user's resources. Not to mention dealing with the user's privacy concerns in a haphazardly manner - if at all.

Alas, this disregard of the user's resources and privacy concerns is a theme we have had for quite a long time. And Google is trying to fix it, is trying to limit our ability to wreak havoc. This is a recurring theme to all the latest Android updates.

Notifications had to be reined in again¹⁾ and again²⁾ and again³⁾ and again⁴⁾ and again⁵⁾. Honestly, we're really treating our users that badly.⁶⁾

And, yet, we still have notification spam. That's disgusting!⁷⁾

Same goes for the battery life. Doze and App Standby, later enhancements to it as well as background execution limits: Only necessary because apps drained the battery and took bandwidth for granted. In short: because apps behaved as if users were only using this one app.

And why did apps behave that way? Because product managers wanted it that way. Because devs didn't care. Because someone intended to make a quick buck.

It's a pity that Google is being forced to go down that route. But I laud Google for doing so and am tremendously thankful for that. But it's a pity nonetheless.

It's not even optimal for users. For example settings concerning one app should be within the app. But since apps misused Android features too often, we have them scattered all over the place. Do you know off the top of your head where you can allow apps to draw on top of the screen?⁸⁾ Where to configure the notifications on your lock screen? Where to make another app the default SMS app?

In short: As a user I am glad that in Android Q I am able to limit background location access.⁹⁾ On the other hand I would have preferred if Google never would have been forced to do it that way in the first place.

It's not Google's fault. We devs are to blame. It's that simple. Time to do better, isn't it? improvements

The post Why Google Limits APIs With Every Android Release: We Devs are to Blame! appeared first on Grokking Android.

What is a DSL

But first things first: What actually is a domain specific language?

A domain specific language is a construct that allows you to create things and set them up in a way that feels more natural and usually comes closer to proper language usage than normal code.

As the name implies, DSLs are only useful in a constrained context - the domain at hand. In contrast to general purpose languages (of which Kotlin of course is one) DSLs apply to a limited set of use cases only.

What then is the benefit of using a DSL over normal constructs? The main benefit is, that domain specific languages provide a more concise and at the same time much better readable API for a specific purpose, compared to the normal general purpose way to achieve the same.

External DSLs

DSLs are nothing new actually. They have been available in other languages for quite a while (on the JVM for example in Groovy and Scala). Actually most DSLs are language independent. Famous examples are SQL, HTML, Gherkin or all those YAML files that are all the rage nowadays.

You can write code using those DSLs in any text editor and later the DSL is then used and parsed by some other code. For example a RDBMS parses SQL, Cucumber parses your Gherkin code, a browser the HTML code and so on. In theory a parser for this could be written in any language. The DSL is external to the language with which it is parsed. Those DSLs are external DSLs. Frederico Tomassetti has compiled a list of more examples of these.

Internal DSLs

But there are also internal DSLs. They are written in the same general purpose language as the DSL itself. The DSL is just a specific way to use the host language. Gradle is an example of an internal DSL - in this case in Groovy.¹⁾

When I’m speaking of Kotlin DSLs, I’m speaking of internal DSLs, of DSLs that make use of specific Kotlin features to achieve their simplicity and benefits.

Examples of Kotlin DSLs

Let’s see some examples of DSLs with Kotlin to show what DSLs are about and why I like them.

KotlinTest

KotlinTest is a library to write better unit tests. One benefit of KotlinTest is the way it allows you to structure your test code as you can see in the following sample:

"when user entered credentials" {
    "and clicked the login button" {
        "and the credentials were valid, then the app" {
            should("switch to main flow") {
                // testing logic goes here :-)
            }
            // more should blocks ...
        }
        // more contexts ...
    }
}

Having done quite some work with Javascript (mostly for the Google Assistant), I started to like Jasmine and gripe about what I used to use on the JVM. Happily with KotlinTest better structured and more easily readable tests for Kotlin projects are no longer an issue.

Anko

I think the Kotlin DSL most well known among Android developers is Anko, especially Anko layouts. If you like to write layouts in code (like in Flutter or React) this can be pretty interesting for you.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    verticalLayout {
        val name = editText()
        button("Say Hello") {
            onClick { toast("Hello, ${name.text}!") }
        }
    }
}

I personally happen to prefer the XML way for layouts and as such am no Anko user. But it’s a well liked project with 13.000 stars on github, so I might be an outlier when it comes to that.²⁾

Koin

The final example to show the value of DSLs is Koin. Koin is a dependency injection framework ³⁾ specific for Kotlin. And it integrates nicely with Android (though it works on standalone JVM projects as well).

Since Koin 2.0 will be even better than the current version, I use samples of the upcoming version. It’s going to be released soon enough for this blog to highlight Koin 2.0.

With Koin you define your dependencies like this:

val appModule = module {
    single { AndroidLogger() as Logger }
    single(name = "mainDispatcher") { Dispatchers.Main as CoroutineDispatcher }
    //...
}
// and somewhere else:
koinApplication {
    useAndroidContext(this@SomeApp)
    loadModules(appModule, loginModule, ...)
}

Again the important thing is, that you can understand easily what is going on here.

There are of course many more examples. Actually DSLs can enhance and ease the use of many libraries, so I expect them to pop up more and more.

But what is common to all these and other samples, is that DSLs are nicely readable. They make the intent of the code obvious and as such they help us achieve understandability and maintainability of our code. That's why I like DSLs - if appropriately designed and judiciously used

Creating your own DSL

Now that we’ve seen sample of DSLs, let’s cover how to actually create one. I will go through some more snippets of code from the many libraries that already offer DSLs and show how they made use of simple Kotlin concepts to achieve the desired result.

Designing a DSL

A DSL is part of your public API that you expose to clients. And since DSLs are part of the overall API, you should also follow common design approaches for APIs.

The first design consideration is, that you always should design with the client usage on your mind. It’s not your job to make the creation of your DSL easy for you. It’s your job to make the usage of your DSL as easy and as intuitive as possible for your client.

The overall guiding principle is, that the proper use of your API should be easy, while any potential misuse should be as hard to make as possible. This is one of the many advices by Joshua Bloch in his presentation on the topic of API design. This one recommendation is probably the most important one, but I strongly recommend to have a look at all of his slides.

One way to ease client development is to shield the client from any technical obstacles. Do not hassle the client with technical details that are of no importance to her.

But what to do if your client might be interested in them. For example information about what went wrong when trying to do a remote call. In that case you could offer a reasonable default behavior for all those that do not care about the details and only make those details available to those clients that want to act differently depending on the cause of the problem.

A DSL specific part of API design is the proper naming of things and of choosing a good syntax. When it comes to naming things, solutions should be kind of obvious. After all you are creating a domain specific language. And as such you should follow the naming conventions of the domain at hand. There also might exist established patterns for naming entities or actions on them. If so, you should follow along to meet client expectations.

With these thoughts in mind you can start designing your DSL. The following paragraphs concentrate on the various elements of the Kotlin language that can help you achieve a nice DSL.

Trailing lambdas

Let’s start with trailing lambdas since they are so common in Kotlin, that you are bound to have seen them.

A trailing lambda is simply syntactic sugar for using function types as arguments to your higher order functions. For example the way you use the should spec style in KotlinTest is made possible by using trailing lambdas. This is a simplified should spec function:

should("show an error message when something bad happened") {
    presenter.doSomething()
    verify {
        view.showError("Some error")
    }
}

And this is how the should method is defined in the KotlinTest code base:

fun should(name: String, test: () -> Unit): TestCase {
    val testCase = TestCase(
            suite = current, name = "should $name", test = test, config = defaultTestCaseConfig)
    current.addTestCase(testCase)
    return testCase
}

As you can see, the argument list of this function expects another function as the last argument, the test argument. And the language designers of Kotlin made it possible to simplify passing the lambdas in when they are the last argument by allowing you to close the argument parenthesis before starting the lambda.

Without trailing lambdas, the should spec above would have looked like that:

should("show an error message when something bad happened", {
    presenter.doSomething()
    verify {
        view.showError("Some error")
    }
})

This is, of course, valid code, but the placements of the parentheses doesn’t look that nice. By allowing you to put the closing parenthesis in front of the lambda argument, the code becomes more readable.

Extension functions

Extension functions are a common pattern that is widely used in existing Kotlin DSLs. They allow you to extend existing classes and to make those extensions only valid within the scope of your DSL.

The next code snippet shows how to write an extension function for the String class. It simply returns a new String in which the original characters are turned into dots. Think of replacing clear text passwords in logs and so on.

fun String.toDots() =
        this.replace(".".toRegex(), "●")

In the Spring routing DSL extension functions on Strings are used to specify handlers for certain paths, to nest different parts of the path or to combine a path with another request predicate. For example to combine a path with the requirement for a certain content type you can use this code:

("/api" and contentType(MediaType.APPLICATION_JSON)) { 
    userHandler.findAll(it) 
}

In this case the and is an extension function on String:

infix fun String.and(other: RequestPredicate): RequestPredicate = path(this).and(other)

We will cover the infix part pretty soon. For now we concentrate on the fact that by providing this extension function, the routing DSL allows us to write code that is readable and quickly understandable.

If you come from Java, you might wonder about this, since String is final and you cannot inherited from it. That’s true, and you still would be able to write extension functions for Java’s String class.

That’s working since the Kotlin compiler transforms extension functions into static functions that take the object in question, in this case the string, as an additional first parameter. As such the code is not really extending the String class, it’s just pretending to do so.

Infix calls

Now the sample just used was still a bit weird since it didn’t look like a normal function call. That’s because the and function is an infix function, denoted by the infix keyword.

Infix functions are functions with exactly one parameter and the infix keyword makes it possible to separate the object and it’s single parameter by the function name. Which is ideal for DSLs since it makes your code more naturally readable.

Instead of having to write the call “somePath”.and(somePredicate) you are able to use "somePath" and somePredicate instead. Much better.

Another sample for infix calls is the following code:

every { view.showNewState(any()) } just runs

The just method tells MockK that a code, that doesn't return any value, must nevertheless run at least once when calling the object under test.

The way to write it like shown above, is only possible because of the use of the infix keyword:

infix fun MockKStubScope.just(runs: Runs) 
        = answers(ConstantAnswer(Unit))

Without the infix keyword one would have to write the MockK definition like this:

every { view.showNewState(any()) }.just(runs)

So we would have to add the dot between the object and it's function and we would have to put the argument within parentheses. I guess you agree that the version that actually uses the infix syntax is much easier to read.

Empty objects

Now let’s have another look at the MockK sample we've just seen. This time we don’t look at the just but at the runs. What is that actually.

every { view.showNewState(any()) } just runs

It turns out that it is an empty object:

object Runs
typealias runs = Runs

An object without any behaviour that exists only to make this infix syntax possible at all.

Now, be careful with this and don’t overdo it. Very often other ways might be better. In this case, though, I like it.

Conventions

You have already seen how extension functions as well as trailing lambdas can help you when writing a DSL, but the following code still looks a bit weird:

"should show an error message when something bad happened" {
    presenter.doSomething()
    verify {
        view.showError("Some error")
    }
}

It is nearly the same test method you have seen a few paragraphs before, but now instead of using the should spec style it's using a string spec style.

This code snippet suggests that you can pass a lambda to an object. As if the object were a function itself. But of course it is not

There is a convention in Kotlin, though, that allows you to treat objects as if they were functions. At least in some very restricted context.

If the object in question has a method named invoke and this function acts as a higher-order funtion, that accepts a function as argument, you can call it like shown above.

A look at the definition of this method makes it easier to understand:

operator fun String.invoke(test: () -> Unit): TestCase {
    val tc = TestCase(suite = rootTestSuite, name = this, test = test, config = defaultTestCaseConfig)
    rootTestSuite.addTestCase(tc)
    return tc
}

You can have multiple invoke methods. And you can use them as extension functions to enhance existing classes, like the String class in this sample.

Lambdas with receivers

You have already seen what trailing lambdas are. But in many cases a normal lambda is not enough. Since DSLs are especially useful for creating and setting up objects or even fully fledged object graphs, we need a way to do exactly that. This is where lambdas with receivers (or function literals with receivers) enter the scene. They allow a domain specific language to create a specific object for you while expecting the configuration of that object in the trailing lambda. But how?

Let's see an example first:

val appModule = module {
    single { AndroidLogger() as Logger }
    single(name = "mainDispatcher") { Dispatchers.Main as CoroutineDispatcher }
    //...
}

What you see here is the Koin 2.0 way to initialize the module graph. Nowhere in this code do you actually create module objects. So the methods must do that for you.

The same mechanism is also what allows Anko to create the view hierarchy for your screens. Let's review the code shown initially in the DSL sample section:

verticalLayout {
    val name = editText()
    button("Say Hello") {
        onClick { toast("Hello, ${name.text}!") }
    }
}

The verticallayout and button blocks are where objects get created and in the respective trailing lambdas you define how to set up those objects.

Within the lambdas you have access to the newly created object as this and thus there is no implicit argument named it.⁴⁾

Now let's see how a trailing lambda looks like from the perspective of the DSL creator. The above modules method definition looks like this:

typealias ModuleDeclaration = Module.() -> Unit

fun module(createdAtStart: Boolean = false, override: Boolean = false, moduleDeclaration: ModuleDeclaration): Module {
    return Module(createdAtStart, override).apply(moduleDeclaration)
}

You can think of function literals with receivers as of local extension functions that are valid only within the scope of the defining function.

As you can see in above's typealias the function type is an extension function on Module. The only thing missing from a normal extension function definition is the name of the function. And this is exactly the same as the name of the argument. So in this case moduleDeclaration (the last argument to the module function on line 3).

On line 4 the function type that was passed into the module function is then passed on to the apply function. But the Module object itself, on which the local extension function is defined, is not passed into the function. Instead it is created within the function right after the return keyword.

Lambdas with receivers might be hard to grasp initially. But they are an important Kotlin concept - not only within the context of DSLs. You can read more about function literals with receivers on Simon Wirtz' blog.

DSLMarker

If you have lambdas with receivers the lambda can access the receiving object with this. But if you have nested structures this can apply to many objects in the hierarchy. And using a method on an object might be wrong outside of the given scope.

That's where the DSLMarker annotation comes into play. If you have multiple annotations the function closest to the call wins. Thus, given the Anko sample above, any methods specific to verticallayout are not accessible within the trailing lambda of the button.

This is great in preventing accidental misuse of your DSL. As you might recall, making your API hard to misuse is one of the fundamental aspects of API design. Luckily Kotlin has us covered!

Let's see it in action in Anko:

inline fun ViewManager.button(text: CharSequence?, init: (@AnkoViewDslMarker android.widget.Button).() -> Unit): android.widget.Button {
    return ankoView(`$$Anko$Factories$Sdk25View`.BUTTON, theme = 0) {
        init()
        setText(text)
    }
}
//... somewhere else:
inline fun Activity.verticalLayout(theme: Int = 0, init: (@AnkoViewDslMarker _LinearLayout).() -> Unit): LinearLayout {
    return ankoView(`$$Anko$Factories$CustomViews`.VERTICAL_LAYOUT_FACTORY, theme, init)
}

And here's the definition of the annotation:

@DslMarker
@Target(AnnotationTarget.TYPE)
annotation class AnkoViewDslMarker

What also might help your DSL

Kotlin allows you to define type aliases, which are a nice way to make your code more explicit. In the MockK example you have seen a type alias for the object Runs which made it possible to use the word in a more natural way.

Another thing to consider is operator overloading. Actually invoke - shown above - is an operator. But there might be others that can come in handy, for example plus or unaryPlus. The library kotlinx.html for example makes use of the unaryPlus operator:

html {
    body {
        div {
            +"a trivial example"
        }
    }
}

Finally I recommend to consider deviating from naming conventions. The routing DSL in Spring for example uses methods to route incoming traffic to certain handler methods. And since they are dealing with HTTP verbs they name those methods in all upper case like GET, PUT, POST and so on. I think in this case the deviation from normal naming conventions is justified and makes the intent of the code more obvious than if the methods were in lower case:

"/api".nest {
    accept(APPLICATION_JSON).nest {
        GET("/users", userHandler::findAll)
    }
}

You can find a more complete example for this in this gist.

Is it worth it?

Now that you have seen how to create a DSL, you still have to consider whether to go for it. And again, there are two aspects to it:

• Should you use a DSL if one exists?
• Should you create a DSL for your API?

Should you use a DSL?

The answer whether to use one or not is pretty easy: of course you should. But, then again, it’s not that easy.

You might have to decide which library to use for a specific problem. And a DSL might help you choose one over the other. But, of course, it’s not the only thing to take into consideration when selecting a library. You still need to be sure that the API fulfills your overall needs, that it is likely to be maintained in the long run (or easy enough to fork and maintain yourself in case the original maintainer(s) wander off).

If two or more libraries fulfill your needs, are more or less equally likely to be maintained in the long run and have an overall nicely designed API I would choose the one that offers the best readability of the client code. If one of those libraries uses a DSL, it’s likely that this one is the lib whose client code is best to maintain and easiest to read. In such a case, a DSL can be the reason to choose one library over the other.

Should you create a DSL?

As nice as a DSL might be, it still comes at a cost. It’s simply more costly to create one. While any API has to be designed carefully, a DSL puts some extra workload on your shoulders. Thus you have to ask yourself whether you should go for it or not.

This depends largely on what your use case is. Is your API for inhouse clients? Is your API used very often or only every now and then?

For libraries things are a tad different. Here the most important questions to ask yourself is: Does your client really benefit of a DSL? Does the domain in question lend itself easily to a DSL and does it offer enough and intuitive concepts to create one? If so, you probably should create one. It will help your library gain traction over those, that do not provide one.

This is even true for Java based libraries. Consider to offer special constructs for Kotlin. The people at Pivotal did so while creating Spring 5. They offer a DSL for Kotlin users even though most of the overall Spring code is written in Java. For me this was one big selling point when considering which Java lib to use for my latest App backend.

It all boils down to this: Is the client code easier to read and write if you provide a DSL?

If yes, by all means go for it. And if not, it’s just not worth it.

But even if you decide not to create a DSL, all the things above might still help you create a nicely designed API that is easy to use. Especially trailing lambdas and function literals with receivers are a very common pattern in Kotlin that might be a good fit for your API - DSL or not.

When’s a DSL a DSL?

By now you hopefully are convinced that DSLs make code more readable and can be worth the effort. You really want to create one, but you’re not sure, if what you’re thinking about is actually a DSL or not. Actually that’s a very tough question, since there are not hard and fast rules that make some code a DSL and some other code not.

In my opinion it all boils down to the question whether the domain offers enough concepts to actually create a meaningful DSL out of it. And if you can create a proper language out of the concepts. After all it’s no DSL if either the domain or the language part of it are missing.

In the end it doesn’t really matter that much. Because the important thing is, that your overall API is easy to use. Whether it’s a proper DSL or just a nicely designed API is not important. Important is, that your API takes the general recommendations for good API design into consideration. That it takes the client front and center while designing the API and that it thus makes the use of your API intuitive and easy and the misuse hard: That’s the problem you have to tackle. And if you do so, your client’s will like to use your API and the resulting code will be easy to maintain.

Want to know more?

There are some good blog posts and some information on the Kotlin website that also cover Kotlin DSLs.

In addition to that I highly recommend reading the book Kotlin in Action. This book is outstanding - and it has a chapter on DSLs. It might be worth to check if it's available as a deal on Mannings site in their year's end sale.

It's always important not to go overboard with new features. That's why in my talks about Kotlin DSLs I always recommend having a look at Márton Braun's repo that discusses the pros and cons of different approaches and provides sample code for all of them. He has nicely summarized the different DSL styles.

Happy coding!

The post Creating Kotlin DSLs appeared first on Grokking Android.

Speaking of where those posts appear: Isn't it funny that the last post appears on a website? Why not use a bot to tout the message? Maybe not so appropriate after all?

Well, so what to make of these post? Are they just trying to convince customers to buy services? Or is there actually something to it?

I believe that there is indeed some truth to voice assistants and chatbots replacing apps. But the overall message is simply wrong. It's more a co-existance of both for a very long future. And they are also not mutually exclusive. Assistant integration into apps or chatbots on websites? Why not? We see this all the time.

Yes, sometimes voice assistants or chatbots are the best way to fulfill a user's need. Sometimes they are not there yet, but you know that they will be soon.

I for one use Google Home more and more to listen to music (mostly streaming to my Chromecast Audio). But I think the Play Music app is much better right now. Do I expect it to stay that way? No. I expect the Play Music app to play an ever lesser role for my music listening experience.

Do I expect the Play Music app to be replaced completely anytime soon? No, I don't. Sometimes I use it on my laptop. Sometimes on my phone, sometimes I stream from there via Chromecast Audio. It depends on where I am and what I am doing right now. Do I expect it to be replaced entirely eventually. Sure: By something else. But that's true for nearly everything. Nothing stays forever. Luckily so!

Now these doomsaying headlines have been around for ages. Though mostly applied to other technologies. Sometimes they are true (as for Kodak for example), but very often they are not. Especially in the media world.

When Radio was announced, it was deemed to be the end for newspapers. Not so. Radio was said to be doomed by TV. Not so. Movie theaters were obviously doomed by downloads. Not so. TV then again was said to be doomed by apps and youtube. Not so. Or just: not so yet?

Even after all those years, the radio is still around. TV is still around. Same goes for PCs and laptops. Heck: Even newspapers and paper books are still around - though I personally think they actually might be doomed, as much as I like them.

All of these still serve a need and are best suited in some cases. But neither of these technologies plays as much of an role as it has been playing in its heydays. And that probably is going to happen to mobile apps - and eventually also to the phones and tablets that run them.

Neither expected them to stay around forever. But for lots of use cases they are definitely still the best choice and will stay that way until something better comes around. For many use cases neither chatbots nor voice apps are a good choice.

BTW: For lots of use cases neither mobiles nor tablets are a good choice - which is why we still use laptops (including me typing this post). So laptops will stay around for some time - but admittedly have lost out for some users. That might happen to apps.

And, of course, for some use cases voice assistants or chatbots are indeed better. For some it depends on the specific need of the user and the specific circumstance the user is in. In all of these cases apps will be used less. Will be downloaded less. But for most use cases, that apps have been used for and for many that might not have been conceived of yet, apps are still strong and the best way to achieve your goal. Apps are going to strive. And voice assistants and chatbots are going to strive as well.

But, of course, there are apps that most likely will be used less. And as with all those other media being somewhat replaced by something that fulfills the needs of people better, that's a good thing. Not for the companies doing those apps, not for the devs, designers and product people having to look for something else (though that shouldn't be a problem right now). But for us users.

It's the same thing as usual: Do not fear the future. Be open to it. Embrace it and adapt to it.

Oh, before I forget it: The sames goes for websites. They won't be replaced either. Neither by apps nor by voice assistants or chatbots.

So in short. Those headlines? I would call B.S. But let's keep that for sh***y politicians.

Note: I am an Google Developer Expert for Android as well as for the Google Assistant. So I have a vested interest in both technologies. But I have much more experience with Android and earn my living mostly with Android. As such I am not unbiased myself

The post Those “mobile apps are doomed” headlines? They are wrong! appeared first on Grokking Android.

About the app

In my home town I usually take the bus when taking our youngest to kindergarten before heading off to work. In winter and also due to some long-lasting street works, one of the two lines near our home is quite late all the time. But naturally unreliably so. So I wonder every morning when to leave for the bus. We do have an app for bus information in Münster - but some limitations of this app make it not really suitable for the task.

Thus an assistant app that tells me when the next busses are due and whether we should hurry up or whether we can idle around a bit more is what I'm going to build. The first version in this post with the Actions SDK. Then in the next post an improved version with Dialogflow.

Here's a sketch of what a conversation with this app should look like:

On the right is what I'm going to speak. On the left are the assistant's answers. The first is by the assistant itself - I changed the color for that one to emphasize the difference. The second and third are responses of the app. After the last response the app finishes - and with this also the current assistant's action. Thanks to botsociety.io, you can even see this website showcasing this prototype.

What is the Actions SDK

The Actions SDK is one way to develop apps for the Google Assistant. As the name of the SDK implies you can create actions which basically are speech snippets of your user and your response to them. Let's go a bit more into the base concepts here.

The relevant things you need to know are:

• Actions
• Intents
• Fulfillment

Actions

An action is a wrapper combining an intent and the fulfillment for this intent. For a truly conversational app, where there's a dialog between the user and the assistant, apps have multiple actions. But often it makes sense to create a one-shot app. In this case the app has only one action and answers directly with the response the user is looking for. The sample app would work well as a one-shot app. I only added one more action to make it a better sample for this post.

Intents

We already know intents from Android. And with Actions on Google they are not much different. An intent specifies what the user intends your app to do.

In contrast to Android, though, you are very limited when it comes to intents with the Actions SDK.

Every app has to define one actions.intent.MAIN intent, that is used to start up your app, if no custom intent is better suited to the invocation phrase. Depending on your kind of app, this intent might directly provide the answer and then stop the app. Or it might kind of introduce the app to the user in some way.

For the start of your app you can also define custom intents and which user utterances trigger that intent. You might even add some parameters to that (for example numbers or a date). And if the Assistant detects that one of those phrases was used by the user, it starts up your app using this intent.

If you were to build a more complex app with the Actions SDK, you would use one intent most of the time: actions.intent.TEXT. Meaning: You have one intent that has to deal with nearly all possible user input. And thus your app would have to decide what to do based on the text spoken or typed in by the user.

There are a few more intents available. For example android.intent.OPTION which is useful if you provide a set of options to the user of which she might select one. But when dealing with user input most of the time you would have to deal with actions.intent.TEXT.

This limitation is the reason why I've written in my intro post about the Assistant, that the Action SDK is mostly useful when you are proficient with natural language processing or have a simple project with a command like interface.

Unless you have some language processing super powers it boils down to this:

⇨ Use the Actions SDK for one-shot apps. These are apps that provide the required answer directly after being invoked and then stop. They give you just this one result. A typical example would be setting a timer to ten minutes.

⇨ For all other apps, for those that are really conversational, where there are multiple paths to follow and where you want your user to provide more information during the conversation, I recommend to use Dialogflow (api.ai) instead of the Actions SDK. I will cover Dialogflow in my next post.

Fulfillments

Fulfillment is just another word for your backend. Every action must be backed by some backend of yours. This is where you generate the text spoken to the user. Or — on devices that have a graphical user interface — that's where you create visual cues for your user.

Of course the response is based on which intent was triggered and what additional cues the user gave in her question.

When Google calls your backend, it provides a Json file that contains plenty of information as you will see later in this post. Some of the things you get access to:

• The spoken text as Google has detected it
• The intent invoked
• The parameters to the intent
• The session id
• Information about the device's capabilities

In this post I'm only going to make use of some of them, but I'm going to cover more aspects in future posts.

The next picture shows where your app — or more precisely: your fulfillment code — fits into the overall picture. The assistant knows which app to call based on the invocation phrase used by the user. It also provides voice recognition of the user utterances and text to speech transformation of your answers to the user. Your app then takes the recognized text and creates an appropriate response for that.

Preparations

When you want to use Actions on Google your account must be prepared for that. You have to do three things:

1. Create a project within the Actions on Google Dev Console
2. Install the gactions command line tool
3. Initialize the project using the gactions tool

In the next paragraphs I'm going to cover those steps.

Create a project within the Action on Google Dev Console

The very first step is to use the Dev Console to create a project. If it's your first project check the terms of the services - since by clicking the "Create Project" button you signify to adhere to them:

Afterwards you have to decide which API to use to build your project:

As you can see, there are three prominent ways to develop apps: The Actions SDK or one of the two services Dialogflow or Converse AI. If you click on "Actions SDK" you will see a tiny popup where you can copy a gactions command. So the next step is to install the gactions command line tool.

Install the gactions command line tool

You can download the gactions tool from Google's site. It's a binary file you can store, wherever you see fit. Make sure to make this file executable (if you're using Linux or Mac OS X) and - since you're going to use this tool a lot - I recommend to add it to your PATH.

If you already had this tool installed, you can use the selfupdate option to update it:

gactions selfupdate

That's all that is needed in this step 🙂

Initialize the project using the gactions tool

The last step is to simply initialize your project. Afterwards you're set to start developing actions using the Actions SDK.

Simply create some folder in which you whish to create the project and then switch to this folder.

Within this folder enter

gactions init

If you have never run gactions before, it will require authorization to access the Actions Console. Simply follow the steps outlined on the command line. After pasting your authorization code into the command line, Google gets your access token which is used for all subsequent communication between the gactions tool and the Actions Console. If you ever want to use another account, simply remove the creds.data file.

The gactions init command will create a file named action.json. This file contains the configuration of your project. In it's current state it's content is not valid. It contains plenty of <INSERT YOUR ... HERE> markers. You are going to fill those in in the remainder of this post.

With this you have finished the preparations and are good to go. So let's start creating an action.

The config file explained

Let's start by looking at the actions.json file that was just created for us:

{
    "actions": [
      {
        "description": "Default Welcome Intent",
        "name": "MAIN",
        "fulfillment": {
          "conversationName": "<INSERT YOUR CONVERSATION NAME HERE>"
        },
        "intent": {
          "name": "actions.intent.MAIN",
          "trigger": {
            "queryPatterns": [
              "talk to <INSERT YOUR NAME HERE>"
            ]
          }
        }
      }
    ],
    "conversations": {
      "<INSERT YOUR CONVERSATION NAME HERE>": {
        "name": "<INSERT YOUR CONVERSATION NAME HERE>",
        "url": "<INSERT YOUR FULLFILLMENT URL HERE>"
      }
    }
}

As you can see, some objects match the concepts explained above. At the top you have the actions object, which contains an array of action objects - each of which contains one intent. The second object is named conversations, which contains a map of conversation objects. I don't know why it's named "conversations", but basically this object covers the description of where to find the app's fulfillment.

You can see the full specs in the reference section for Actions on Google.

The config file of the sample app

The sample app has one intent to deal with the start of the app - the actions.intent.MAIN intent.

This app is a good example for a one-shot app - meaning it would provide the answer directly with the actions.intent.MAIN intent and finish itself directly after giving the answer.

To make this tutorial more useful, I've added the possibility for the user to acknowledge the answer of the app before it ends itself and gives the control back to the assistant. And - if the user didn't understand the answer - she can ask for a repetition.

Thus there is one intent of type actions.intent.TEXT that deals with both of these follow-up responses by the user and that also provides an answer in case the app doesn't understand the user's intention.

The resulting actions part looks now like this:

{
  "actions": [
    {
      "description": "Default Welcome Intent",
      "name": "MAIN",
      "fulfillment": {
        "conversationName": "do-i-have-to-rush"
      },
      "intent": {
        "name": "actions.intent.MAIN",
        "trigger": {
          "queryPatterns": [
            "talk to let's rush",
            "let's rush",
            "do i have to rush",
            "do i have to hurry",
            "start let's rush"
          ]
        }
      }
    },
    {
      "description": "Everything Else Intent",
      "name": "allElse",
      "fulfillment": {
        "conversationName": "do-i-have-to-rush"
      },
      "intent": {
        "name": "actions.intent.TEXT"
      }
    }
  ],
  "conversations": {
    "do-i-have-to-rush": {
      "name": "do-i-have-to-rush",
      "url": "<INSERT YOUR FULLFILLMENT URL HERE>"
  	}
  }
}

The intent represents the type of information the user tells the app. You first have to specify a name for this intent and then you have to define how this intent can be triggered by the user. So basically what the user has to say, in order for the assistant to select this intent.

As you can see from the Json above, the trigger contains an array of possible phrases. You can use it for custom intents - but also for the initial, the main intent. My sample app has the name "Do I have to Rush".¹⁾ But the user might use other phrases to trigger your app. In the prototype shown at the beginning of this post, I am using "Let's rush". And that is working as well because I added that phrase to the trigger section of the intent.

For actions.intent.TEXT intents you do not need to specify trigger phrases - since this intent gets called automatically for follow-up phrases of the user.

The above file is still incomplete. While the fulfillments link to a conversation, the conversation's URL is still not set. I will add that information after I've created the function in the next section. I am using Cloud Functions for Firebase - and the URL can only be set after deploying for the first time.

About time to delve into the fulfillment code.

The fulfillment code

In the config file you specified how many and which intents you have. In your fulfillment you have to provide the responses to these intents. That is: You tell the assistant what to say to the user and - if the device is capable of those - what visual elements to show the user.

For the fulfillment's backend I am going to use Firebase's Cloud Functions with Javascript. Please see my introduction tp Cloud Functions for Firebase and especially the section on setting up your Cloud Functions project to create the necessary files and project structure.

If you want to follow along set up your project as described in my previous post.²⁾

The Actions On Google Client Library

Google provides us with an Actions on Google client library for Javascript. For the code in this tutorial I'm making use of that lib.

Note that there is also an unofficial Kotlin port available. I haven't had a look at it, since I prefer to use Cloud Functions. Anyway: If anyone has experience with it, please let me know in the comments or on social media.

Assuming you have created the necessary structure with firebase init the next step is to add Google's library to your project.

The simplest way to do so, is to use npm install within the functions folder of your project:

npm install actions-on-google

You will get a result telling you the number of installed packages. And your package.json file afterwards contains this additional dependency:

{
//...
  "dependencies": {
    "actions-on-google": "^1.5.0",
    //...
  },
//...
}

1.5.0 is the most recent version while writing this post. But when you read this, the newest version might very well have a higher version number since Google is eagerly working on everything related to the Google Assistant.

If you want to update to a newer version, you can update the version using

npm update actions-on-google

The fulfillment function

When it comes to the actual function code, you have to do three things:

1. Initialize the Assistant library
2. Create a mapping from intents to functions
3. Write a function for every intent

Your function after firebase init

You already should have code similar to this in your project if you set up Cloud Functions correctly:

const functions = require('firebase-functions');

/**
 * This function is exposed via Firebase Cloud Functions.
 * It determines the next busses leaving from the
 * closest busstop to our home.
 *
 * You normally create one function for all intents. If you
 * want to use more functions, you have to configure all
 * those fulfillment endpoints.
 *
 * Note: Your fulfillment must respond within five seconds.
 * For details see the blue box at the top of this page:
 * https://developers.google.com/actions/sdk/deploy-fulfillment
 */
exports.shouldIRush = functions.https.onRequest((request, response) => {
   // some generated stuff you can safely delete
}

Add the Google Actions on Google SDK

The very first step is to add your the actions-on-google dependency at the top and to create the ActionsSdkApp object within the function:

const functions = require('firebase-functions');
var ActionsSdkApp = require('actions-on-google').ActionsSdkApp;

/**
 * ...
 */
exports.shouldIRush = functions.https.onRequest((request, response) => {
    let app = new ActionsSdkApp({request, response});
    // ...
}

Note that you are using a specific part of the actions-on-google lib. You only need the ActionsSdkApp. In my next post about Dialogflow this will change and you will use the DialogflowApp instead. You must not forget the specific part you are interested in nor must you use the wrong one. One thing you need to know: In its samples, Google usually uses an ActionsSdk alias for the ActionsSdkApp class.

When you have added the lib and create the object, you can use the app object to query for information about the request and to provide the answer to the user.

Create the mapping from intents to your handler functions

As you've seen in the action.json file, the sample project has a main and an allElse action. So first, let's create empty functions for those two action's intents. Next we create a mapping from the two intents to these two functions. Note that the mapping is based on the intent name and not the action name. Finally call app.handleRequest() with this mapping to allow the lib to do it's magic:

exports.shouldIRush = functions.https.onRequest((request, response) => {
  let app = new ActionsSdkApp({request, response});
  //..
  function handleMainIntent() {
  }
  
  function handleTextIntent() {
  }
  
  // finally: create map and handle request
  // map all intents to specific functions
  let actionMap = new Map();
  actionMap.set(app.StandardIntents.MAIN, handleMainIntent);
  // all follow-up requests will trigger the next intent.
  // Be sure to include it.
  actionMap.set(app.StandardIntents.TEXT, handleTextIntent);
  
  // apply this map and let the sdk parse and handle the request
  // and your responses
  app.handleRequest(actionMap);
}

Write a function for every intent

Now I'm not going to show all I've done within those functions. I simply highlight some specific aspects, that are important to understand the Actions SDK.

For my intents I simply call the usecase:

function handleMainIntent() {
    console.log(`starting mainIntent - ${getDebugInfo()} - at: ${new Date()}`);
    usecase.callApiAndPrepareResponse(new UsecaseCallback());
}

function handleTextIntent() {
    console.log(`starting textIntent - ${getDebugInfo()} - at: ${new Date()}`);
    usecase.handleFollowUpPhrases(app.getRawInput(), new UsecaseCallback());
}

The usecase generates the response that the assistant should present to the user. With those texts it then calls the appropriate methods of the callback object. The callback object passed to the usecase is of this type:

class UsecaseCallback {
    answerNormalRequestSuccessfully(answerText) {
        app.ask(answerText);
    }
    answerNormalRequestWithErrorMessage(errorMessage) {
        app.ask(errorMessage);
    }
    endConversation() {
        app.tell('See you!');
    }
    reactToUnknownPhrase() {
        // If nothing matches, you might consider providing some help
        // to the user; I omit this for this simple usecase.
        app.ask('I\'m sorry, but I\'m not able to help you with this.');
    }
}

So sometimes I call app.ask() with a text and in one case I call app.tell(). Even though the former is named "ask" it doesn't necessarily mean it has to be a question. In my case the answer is presented using ask(). But ask() keeps the conversation alive. It basically expect another user reaction. The tell() method on the other hand doesn't expect a user reaction. In fact it closes the conversation and passes the baton back to the Assistant itself.

Of course there are more options available than just to ask or to tell, but I won't go into them.

From the code above you can see, that I also have a function to generate some debugging information:

function getDebugInfo() {
    // you can get some userId - but for getting the name, you would
    // need the appropriate permission.
    // be very careful what you use in production here;
    // logging too much can cause privacy issues
    return `user: ${app.getUser().userId} - conversation: ${app.getConversationId()}`;
}

While the usefulness of the userId depends on a few factors, the conversationId is nearly always useful. For one, you can use it to store conversation state on your backend. Since you only have limited possibilities to keep a conversational state with Actions on Google this id can be used as a key for that.

A second good use for the conversationId is for tracking down problems by using this id within all of your log messages and thus enabling you to join all log messages of one conversation together.

Deploy the fulfillment function to Firebase

To deploy your fulfillment function, simply call

firebase deploy

Th deployment lasts a few seconds and when it's done, you get the function URL, you can use in the conversations section of the action.json file. Simply copy this url and replace the <INSERT YOUR FULFILLMENT URL HERE> placeholder with your url:

{
//...
  "conversations": {
    "do-i-have-to-rush": {
      "name": "do-i-have-to-rush",
      "url": "https://us-central1-gcloinudProjectId.cloudfunctions.net/yourFunction"
    }
  }
//...
}

Deploying an app to the Actions Console

If you have deployed your code to Firebase and configured your action.json file, all you have to do, is to deploy your app to the Actions Console.

Actually all Google needs, is your actions.json file - or files in case of internationalized apps. It's not as if you deploy code to the Actions Console. You only define your actions and where to find your code.

So to upload the newest version of your file simply issue this command:

gactions update --action_package action.json --project yourActionsConsoleId

Now if you do not know the Action Console id anymore, simply go the the Actions Console, select the project and click on the gear icon. Then select "Project settings" to see the project id:

Testing the Actions SDK based app

Google provides a web-based testing tool for actions which is really a good way to test and demonstrate your app:

You can test your app also on your Google Home, your Android or iOS devices and on any other device that offers the assistant (for example the AIY based devices). To do so, those devices must use the same account and must match the locale of your test.

But before you can test, you must enable the test. The easiest way is to use the command line:

gactions test --action_package action.json --project yourActionsConsoleId

But you can also enable testing in the Actions Console. Simply go to your project and click on the "Simulator" link in the menu on the left and than click the "Start Testing" button.

While writing this, I do not see this button for one project or get an error when trying to enable testing via command line due to a glitch on Google's side. As I've mentioned, Google is working a lot on Actions on Google. The downside of this is, that there are occassional hiccups. One this week, one last week. In both cases, though, the response by the Google team (alerted via the Actions on Google community on Google+) was quick and helpful.

Sample project

For more detailed code see my ActionsSDK sample project on github. On github you find the full implementation of the sample app outlined at the beginning of this post.

After cloning the sample project, you have to install all the packages. Switch into the functions folder of the project and issue the following command:

npm install

The project only contains the cloud function's code and the action.json file. So be sure to follow the relevant steps of this tutorial for deploying the function and deploying the project to the Actions Console.

Summary

Creating this project was fun. But it also made obvious the current limitations with the Actions SDK approach. To judge for yourself have a look at the timetable-usecase.js file. That's not the best and most flexible way to react to user phrases 🙂

Thus for anything other than one-shot apps I recommend to use Dialogflow. In one of my next posts, I'm going to improve upon this app by switching to Dialogflow.

Until next time!

Ok, Google dear reader, what's your take on this? What are you going to do with the Actions SDK? Please let me know.

The post Using the Actions SDK to Develop for the Google Assistant appeared first on Grokking Android.

What are Cloud Functions for Firebase

Cloud Functions is a node.js based offering where you can expose stateless services. You can use it to react to certain Firebase events (not covered in this post) or to react to http events. They are more or less the same as Google Cloud Functions but are triggered by other events. Of course you have access to all those other Firebase services from within Cloud Functions for Firebase.

Warning: I am only describing functions triggered by http. I do not deal with the realtime database or the storage triggers and so on. If you're interested in the full list of possible triggers, see the official documentation.

Setting Cloud Functions up

First of all: You need npm installed. npm is a package manager for Javascript modules and (command line) tools. It's part of the node.js ecosystem - and thus you install it by installing node.js. I assume you have node.js and npm installed. Otherwise go to the node.js website and click on the big download links to install it (or use the respective Linux or OS X tools for installing packages). Make sure, you use the LTS version - the newest version is not supported by Firebase.

Install the Firebase command line tools

After you have npm installed, you need to install the Firebase tools. If you're using Firebase Hosting, you should have those tools already installed. If not, simply install them using npm:

npm install -g firebase-tools

You can use the same command to update the Firebase command line tools later on. Since Google updates them frequently, Google recommends to use the latest version. So even if you already have them installed, you might want to update.

To check which version you're using, use

firebase --version

Authorize the firebase command line tools

The next step is to authorize the command line tools to use your credentials. Start this process by using

firebase login

The tool asks whether you want to provide anonymous stats and afterwards starts the browser (should this not work automatically, it prints a rather longish URL to copy into your browser). As usual you get a list of things the command line tools need to do and you can grant the necessary permission to do so, by clicking "Allow".

Initializing project

If you want to create a new project in the web-based Firebase Console, now would be the right time to do so. Afterwards switch back to the command line.

Unless you haven't done so already, you should switch to the folder in which you want to create your Cloud Functions for Firebase project. Within this folder create the project by calling

firebase init

You will see something like this:

You can navigate to the second option using the up/down keys on your keyboard and then select "Functions: Configure and deploy Cloud Functions" by pressing space when the arrow points to this option. With pressing space again, you can deselect selected options.

In the next step you have to select the Firebase project you want your Cloud Functions to be associated with. Again use your arrow keys and space to select the appropriate option. Even though there is a "create a new project" option, I recommend to create the project in the webbased Firebase console before running firebase init. You can abort the tool at any time with Ctrl-D or Ctrl-C.

Afterwards the tool creates the necessary project structure for creating Cloud Functions and deploying them to Firebase.

The Firebase command line tool creates the npm dependencies by default, but before it does so, it asks you, whether it should do so. I recommend installing the dependencies, you will need them anyway. So simply hit enter when the question pops up.

If you are using Sonartype or any other private npm repository, you shouldn't install the dependencies. Instead you have to change the created package.json file after the project has been set up, so that it points to your repository url.

Structure of a Cloud Functions project

After having set up the project the project structure looks like this:

The top level folder contains relevant information for Firebase. The .firebaserc file for example contains the information to which Firebase project the function should be deployed.

The functions folder contains your Javascript code. The starting point for your project is the file index.js, though you might have more Javascript files than just this one. Within the functions folder there's also the file package.json, that contains information about how to package your project.

Finally there's the sub-folder node_modules that contains all the necessary dependencies of your project. Even without anything added by yourself, it contains already quite a lot of modules.

Signature of the called function

You need to add the firebase-functions module to your code and - obviously - the code of your function.

The bare minimum looks like this:

const functions = require('firebase-functions');

exports.yourFunction = functions.https.onRequest((req, res) => {
    // your code goes here
});

With this code, you export the function yourFunction. While I will cover deployment a bit down, for now it's enough to know that the firebase command line tool deploys all exported functions by default. You can use as many functions as you like within your index.js. Just remember to keep your code concise and tidy and consider using your own modules to keep the logic separate from your functions.

The req and res paramters are the same Request and Response objects you might know from Express - a very common framework to develop webapps with node.js.

With the Request object you can get more information about the request. For example you can get access to the headers and the body of the http request or to the the query string used for the request.

You need the Response object to generate the answer you want to send back to the client. You can set the statuscode, set headers and a body in your response.

I strongly recommend to use strict mode with Javascript. Otherwise Javascript is simply too forgiving, which will hurt you more often than not. One important thing strict mode takes care of, is to prevent your code from accidentally creating global variables.

With strict mode enabled and with making use of some features of the respective objects, the typical Hello World sample could look like this:

"use strict";

const functions = require('firebase-functions');

exports.yourFunction = functions.https.onRequest((req, res) => {
    let name;
    if (req.query.name) {
        name = req.query.name;
    }
    else {
        name = "World";
    }
    res.contentType("application/json");
    res.send(JSON.stringify({ "result": "Hello " + name }));
    res.status(200);
    res.end();
});

Unit testing a function

Unit testing Cloud Functions is not really a problem. You have to call your function and assert that it does what you want it to do. So basically you have to verify, that the res object is in the expected state after your function has been executed.

Bofore coding tests, you need to have the necessary test libs. I'm using Mocha for running the tests and Chai for testing assertions in a nice way using Chai's should assertion style.

I recommend to install Mocha globally and Chai locally:

npm install -g mocha
npm install -D chai

The option -D ensures that the lib is not packaged when you deploy your function, while still being available when running your tests.

Mocha expects test code to be within a subfolder named test. I consider this to be a good default and thus follow along. To get access to my system under test, I simply have to point to the parent directory, when importing the function:

const subject = require("../index.js")

For testing the function you have to create mock objects for the request and response objects you pass into the function. If you use the realtime database, storage or anything else from within your functions, you have to mock these as well. You could use Sinon for that, but Javascript makes mocking very easy. So sometimes that's not even necessary.

For example I create a mock status() function on the response object, since I set the status using this method in my code.

"use strict";

const chai = require('chai');

describe("Sample Functions", function () {
    const subject = require("../index.js")
    let req;
    let res;
    chai.should();

    beforeEach(function () {
        req = {
            "query": {}
        };
        res = {
            "shadow": {
                "statusCode": 999,
                "noOfEndCalls": 0,
                "contentType": ""
            },
            body: {},
            contentType: function(contentType) {
                this.shadow.contentType = contentType;
            },
            status: function (statuscode) {
                this.shadow.statusCode = statuscode;
            },
            end: function() {
                this.shadow.noOfEndCalls++;
            },
            send: function(bodyText) {
                this.body = JSON.parse(bodyText);
            }
        };
    });

    it('someFunctions should return Hello World in body json', function () {
        subject.yourFunction(req, res);
        verifyCommonResults(res);
        let expected = { "result": "Hello World" };
    });

    it('someFunctions should return Hello Assistant in body json', function () {
        req = {
            "query": {
                "name": "Assistant"
            }
        };
        subject.yourFunction(req, res);
        verifyCommonResults(res);
        let expected = { "result": "Hello Assistant" };
        res.body.should.eql(expected);
    });

    function verifyCommonResults(res) {
        res.shadow.statusCode.should.eql(200);
        res.shadow.noOfEndCalls.should.eql(1);
        res.shadow.contentType.should.eql("application/json");
    }
});

If you installed mocha globally, you can now run the test using

mocha test

Another option is to define a script section at the root level in your package.json file and use npm test to run your tests instead:

"scripts": {
  "test": "mocha test"
}

Mocking outbound http calls

An important thing is to mock outbound traffic if you connect to an external endpoint. For this I use Nock. Nock is very powerful and comes with a good documentation about all of nock's options. A very simply example looks like this:

var nock = require('nock');
var api = nock('http://myexternalapi.com')
    .get('/mytestpath/')
    .reply(200, '{"dummy": "Hello World"}');

The next request to http://myexternalapi.com/mytestpath/ would then be answered with the Json specified.

Running a function locally

Before deploying a function you should test it locally. The command firebase serve does just that:

firebase serve --only function

If you forget to add the --only function part, you will get a rather useless error message:

"Error: An unexpected error has occurred."

Alas, starting the local server is not really a very fast option. You have to wait a few seconds until a localhost URL is printed for your function. After that, you can use it - either by loading the URL in your browser, using Postman or by using curl.

There won't be a log file, but any console.log() output of your code will be printed directly to the command line. Not perfect, but sufficient for local testing.

Even though the local deployment is too slow for my liking, it really helps detect flaws - especially in the begining, when you're not entirely sure what your mock request and response objects should look like. I strongly recommend to test locally before deploying to the Firebase cloud.

Deploying a function

The deployment of your function is easily done by using this command:

firebase deploy --only functions

The tool checks if the project has been set up correctly and is backed by a Firebase project in the cloud, then zips your project and uploads it. Finally it prints the URL at which your function can be accessed.

The deploy tool also prints the URL to the project console. You can use the project console to see how often each of your functions was executed, to see the logs and to see the total number of invocations. Depending on your plan this might be important information for your billing.

For accessing the logs you might prefer the command line option:

firebase functions:log --only yourFunction

The --only yourFunction part limits the output to the lines that belong to this specific function. You can also omit this option, in which case you get all the logs.

Wrap up

So with this, you should have a good understanding of what Cloud Functions for Firebase is and how to use it. And - very important - how to properly test the functions you deploy to the Firebase cloud.

I am going to use those functions in my upcoming tutorials about developing apps for the Google Assistant. But all in all they can be used wherever a stateless service makes sense. Depending on your workload and your use case, serverless computing can be a very cost-effective solution since you pay exactly for what you need.

Until next time: Happy coding!

The post A Primer on Cloud Functions for Firebase appeared first on Grokking Android.

Different types of Interfaces

Conversational interfaces is a very broad term. It covers all kind of chats whether voice is used or not up to pure voice interfaces like those used in Google Home.

Actions on Google supports text based interfaces - and depending on the capabilities of the devices - a limited set of visual feedback and touchable actions. I will cover those differences and how to detect which capabilities the device in question has, in later posts. On a mobile the text can be entered either by keyboard or by voice. With Google Home it obviously can only be entered by speaking to the device.

BTW: You can expect the assistant to appear in other devices as well. Be it IoT devices, cars or anything else where a voice interface can be useful. As you have seen in the first picture of this post, Google's AIY kit itself uses Actions on Google (or can be made to use it). How to achieve this is also the topic of an upcoming post.

Two SDKs for The Google Assistant

When it comes to the Google Assistant, there are two very different offerings by Google:

• The Assistant SDK and
• Actions on Google

Assistant SDK

With the Assistant SDK you can enable devices to embed the Google Assistant. This means that it allows you to add the Google Assistant to a device made by you. It also allows you to change the way the Assistant is triggered on your device - for example you can use a button press instead of the "OK, Google" phrase.

The SDK is gRPC based, which is a protocol buffer based message exchange protocol. It has tons of bindings for a plethora of languages. As a sample (and for practical use as well) complete Python bindings for certain linux based architectures already exist.

If you are creating devices and want to integrate the Assistant into those, than the Assistant SDK is the SDK of your choice. The AIY kit, shown in the picture above, is running the Assistant SDK on a Raspberry Pi. I will get into this SDK in a follow-up post.

Actions on Google

With Actions on Google your can create apps for the Google Assistant. The remainder of this post is all about this option.

Two options to use Actions on Google

When developing apps for the Google Assistant, there too exist two options:

• Use the Actions SDK directly
• Use a service on top of the Actions SDK

Google gives you a recommendation as to when to use which option on its "Build an app in 30 minutes" guide.²⁾

Using the Actions SDK

The Actions SDK allows you to directly access the recognized user text and to deal with it in your backend. It is suited for either very simple projects with clear commands or if you are sufficiently proficient in natural language processing.

Edit (Oct. 12th, 2017): I have just published a detailled post about how to start developing apps for the Google Assistant using the Actions SDK.

Using api.ai or other services on top of the Actions SDK

Most often using a service is the better option. It's not that the Actions SDK itself is particularly complex. The problem lies more in how to detect what the user intends with his response and how to parse the text to get relevant data. This is where those services shine. You enter some sample responses by the user and the services then not only understands these sentences but many, many more that resemble those sentences but use different wording, a different word order or a combination of both. And they extract the data you need in an easily accessible format. Consider understanding dates - which is not even the most complex example. You have to understand "next week", a specific date given, abbreviations, omissions and many more. That's the real value of these services.

One such service is api.ai which was bought by Google last fall. As such it's only natural that this service supports Actions on Google quite nicely. In addition to this you can use api.ai also for other platforms like Alexa, Cortana, Facebook Messenger and many more. I will cover api.ai thoroughly in future posts.

Edit (Oct. 10th, 2017): As of today api.ai has been renamed to Dialogflow. The domain has also changed from api.ai to dialogflow.com.

You are not limited to api.ai, though. One contender is converse.ai which I haven't had the opportunity to test, yet. The visual design of converse.ai's conversation flow has some appeal but whether it's practical and overall as good as api.ai, I cannot tell. But hopefully I will be able to evaluate it while continuing with my Actions on Google posts.

Let's put things into perspective

Even though conversational interfaces seem to be all the rage lately, they are not really new.

Actually they are quite old. Eliza was programmed by Joseph Weizenbaum in the sixties and created quite a stir back then. You can try it out on dozens on websites for yourself.

My first experience was the fictional interface shown in the film Wargames, 1983: You can see the part where this screenshot is taken from on YouTube.³⁾

And of course there was Clippy in the late nineties, the worst assistant ever:

So if they are not new, why then are they all the rage? Well, luckily we have progressed from there on and nowadays we have all kind of chatbots integrated into messengers and other communication tools, we have website assistants that pop up if we ponder for a while on a particular page and we have true voice only interfaces like Amazon's Alexa and Google Home.

And those are powered by a much better understanding of human language, of the intents of the user and how to find and combine important entities of the user's spoken text.

The Google assistant works for voice only devices (like Google Home) or with some visual add ons on phones or other devices with a touchscreen.

Wrap up

This was a very quick rundown of the Actions on Google options. In coming posts I am going to show you the base concepts like actions, intents and fulfillment, how to make use of api.ai / Dialogflow, what tools and libraries Google provides, how to connect to your home devices, what permissions are needed for within the Assistant and how to make use of the Assistant from within Android Things.

And in the meantime I'm going to talk about this stuff on upcoming devfests

Stay tuned!

Footnotes[+]

Footnotes

↑1	Right now it's available in the US, Canada, UK, France, Japan and Germany. But there's still a lot of place for improvement. Really, Google, you have to move faster when it comes to international rollouts!
↑2	30 mins? Seriously? This reminds me of those infamous "Teach yourself Java in 24 hours" book series. Never liked these titles!
↑3	Okay, those were the eighties, so it might feel strange to most of you

The post Quick Intro Into Actions on Google appeared first on Grokking Android.

As all the others I started out with buying one of the developer kits and then making some lights blink. Nice. But, well, if I have to be honest with myself, that was fun but actually of only limited use  Then again, fun is why I started out coding, so maybe not so limited after all.

Still, as I nevertheless wanted to create something more useful, now came the hard part: What to actually create? What could keep me going?

Since my kids obviously play a huge role in my life, I used it to play "Happy birthday" and "Auld Lang Syne" on my son's birthday (which incidentally is on January, 1st) next. Better, but given the dismal sound quality, still not good enough.

After some googling around, skimming makers books at the local library and looking at Adafruit's (US), Pimoroni's (UK), Kiwi Electronic's (NL) and Flikto Elektronik's (D) websites, I decided to do some kind of vehicle. I thought, that's something that also might get the attention of my kids - and after showing them some pics on the web, they indeed agreed: That's the thing to go forward with.

First idea

The first idea was to use a ready made kit. This kit would provide all the necessary hardware like motors, motor drivers, wheels and so on. The only exception would be the Raspberry Pi (the developer board I chose to buy) itself.

That's nice enough and proved to be quite a good starting point. But then I saw more self-made ideas. Having to build more ourselves is much better suited for us as a family. Especially since it gives the kids much more space to contribute to the overall project. For some nice pics see this Google image search for "Lego car raspberry pi".

This car with Lego looked pretty impressive. Since the kids love to build and rebuild stuff with Lego this project of a Lego™ chassis is the role-model for our project. The kids could build (and rebuild) the chassis. They could also help connect some parts of the electronics. My role would be limited to ordering (and paying for) the stuff, soldering a bit (I hate soldering and try to get around it as much as possible) and, obviously, coding the apps.

To quickly get a grasp of what the coding might involve, I still bought a complete kit (the STS-PI by Pimoroni) as some kind of MVP for our RC car. As you can see it's a rather simple construction - which suited me for getting started.

But it was obvious from the beginning that this would only be a start to test out some stuff and that the real thing would come later.

In the following sections I'm roughly outlining some thoughts about the project so far - and some of the decisions already made.

Battery or cable

Actually that's no question. The raspberry will be mounted on the chassis and the car must function without being tethered to any power plug or - even worse - my developer laptop. So I'm going to use a battery. For the quick prototype it will simply be a power bank. For the final thing it's going to be proper batteries that are powerful enough to power the more powerful motors of the final car as well as the Raspberry Pi.

Controlling the car

First explorations revealed that both Bluetooth and Wifi Peer to Peer are not available on Android Things, yet. I very much hope they will be supported soon!

Building a proper radio controller is beyond my beginner's grasp of hardware related stuff - and it surely doesn't follow the minimum viable product approach. My kids (and I!) want to see a car going - no need to wait needlessly long

Thus I am going to use Wifi where both the car and the remote controller handheld are in the same network. But if I am going to use DNS-SD I have not yet decided - nor do I know if this works on Android Things.

Since I might eventually change to some kind of radio controller, the app must be flexible enough to accommodate for this change.

Abstracting the car

I already mentioned that I have a kit for quickly getting to first results and that we later on want to built a car with Lego. Not sure how much they will differ in the end, but it's very likely that they will have differing characteristics. My remote control shouldn't need to know about this - and ideally most of the app on the car neither.

Abstracting the device

Android Things runs on multiple devices. There are three developer kits already available and two currently listed as coming soon. And I expect more to come. Even though I currently only own two Raspberry Pi boards, I want this project to be agnostic to the actual device the car is running on. Thus I will also abstract away some of the Android Things characteristics.

Family requirements

We have two kids and thus have to have two vehicles (or suffer endless bickering). That one's easy: We will have the Pimoroni kit and the self-built one.

For the same reason both cars must be usable at the same time. Which has some ramifications for the apps. The remote controls must be able to steer both cars. But of course only one at a time. Maybe we even need some parental mode to prevent the kids switching cars on their own and thereby annoying the other one. You have no idea how big a role conflict prevention plays in my daily family life

Preliminary requirements

To start with, these are the project's requirements. They will evolve and be adapted while going along and I expect more to be appended. But for now those are the basics:

• The system must support multiple cars
• The system must support multiple Android handhelds as remote controls
• The system must support different Android Things devices to be used within the vehicles

Next steps

The first item going to be implemented will be to make the Pimoroni kit move properly - while keeping the abstractions in mind. At first it will just run a preprogrammed sequence to showcase that the car can go forward, backward and can turn around.

I haven't decided yet about the next steps after this, but most likely I will first create the remote control before building the second car. But with the kids acting like product owners, you never know.

BTW: Some preparations have already been done:

We ordered a motor driver. We ordered some wheels and motors and I even soldered some wires onto them. We ordered some Lego bricks with holes to fasten the motor properly. Alas, those Lego parts are not here, yet. Which means we cannot start constructing the chassis

But apart from that, not much has been done yet. I guess it's about time to get my hands dirty and to start coding.

Stay tuned! You will hear about our progress.

And in the meantime: Keep coding! Keep tinkering!

Lego™ is a trademark of The LEGO Group. Android™ is a trademark of Google.

The post Android Things: Remote Controlled Car – What’s Coming Up appeared first on Grokking Android.

<attr name="layout_constraintLeft_toLeftOf" format="reference|enum">...</attr>
<attr name="layout_constraintLeft_toRightOf" format="reference|enum">...</attr>
<attr name="layout_constraintRight_toLeftOf" format="reference|enum">...</attr>
<attr name="layout_constraintRight_toRightOf" format="reference|enum">...</attr>
<attr name="layout_constraintTop_toTopOf" format="reference|enum">...</attr>
<attr name="layout_constraintTop_toBottomOf" format="reference|enum">...</attr>
<attr name="layout_constraintBottom_toTopOf" format="reference|enum">...</attr>
<attr name="layout_constraintBottom_toBottomOf" format="reference|enum">...</attr>
<attr name="layout_constraintBaseline_toBaselineOf" format="reference|enum">...</attr>
<attr name="layout_constraintStart_toEndOf" format="reference|enum">...</attr>
<attr name="layout_constraintStart_toStartOf" format="reference|enum">...</attr>
<attr name="layout_constraintEnd_toStartOf" format="reference|enum">...</attr>
<attr name="layout_constraintEnd_toEndOf" format="reference|enum">...</attr>

But ConstraintLayout is flexible enough to get your view aligned to the center of another view without such an attribute. Even though the solutions is a tad hacky

Say you have view A and want another view B to left-align to the center of A. To achieve this you can add yet another view C. Align both edges of C to the respective edges of A. C is thus centered to A. Now you can align the left edge of B to the right edge of C. Finally set the visibility of the helper view C to View.GONE - and you are done.

Here's the screen showing it before the view is set to View.GONE:

And this is the desired result after setting the helper view to View.GONE:

Have a look at this gist of the actual layout file. It probably makes the steps more obvious.

Keep in mind: You cannot use a view and simply set it's layout_width and layout_height to 0dp - since this is equivalent to stretching within a ConstraintLayout. To make a view have a height and width of zero, you have to set it's visibility to GONE. That's the only way to achieve this!

I think I mentioned it already in my previous ConstraintLayout article. But maybe it's time to repeat myself: I really like what Google's devs are doing with ConstraintLayout. Keep up the good work

The post Android’s ConstraintLayout: Align One View’s Edge to Another View’s Center appeared first on Grokking Android.

In this post I am going to highlight what I like about the new layout and the new editor.

What's to like about the new ConstraintLayout

With the new layout there's a lot to like. Here are my favorite things about it:

• The aim to help us developers
• The availability of the stretched width/height of its children
• The use of guidelines
• The fact that is doesn't feel as weird as Auto Layout

Now let me dig a bit more into each of these.

The aim to help us developers

At this years Google IO talk "Android Layouts: a new world" Nicolas Roard and John Hoford gave two reasons for introducing a new layout:

• To make handling complex screen designs easier
• To improve the performance of complex layouts

And both are, of course, highly appreciated.

If you have a complex layout, things can get pretty difficult to manage. Moving stuff around in a RelativeLayout is bound to break a lot of other stuff. That's what they cited at IO. And it is true. So if this new layout help us with this, I'm all for it.

On the other hand things are currently not as bad, as they made them out to be. And the nesting can actually help you understand certain parts of the layout better since they are grouped and broken down into smaller parts. More practice with the new layout will show, if this really makes that much of a difference when maintaining screens.

In my opinion more important is the second motivation: To improve the performance. As users we all want the apps on our devices to run as smoothly as possible. And as developers we want to deliver this experience to our users. Thus, I'm all for it.

When it comes to performance improvements there is never any limit for additional improvements. So if Google helps us, I'm more than happy. Maybe this way the ConstraintLayout also reduces the need for some custom views or layouts.

A bit down I'm going to have a look at the actual performance of the ConstraintLayout as it is today. It definitely needs more work. But the goal is laudable and the final implementation surely will fare much better than the current one. Mind you, we are talking about an alpha version here!

The availability of the stretched width/height of its children

The new stretched (or "any size") appearance is better than match_parent in the context of this new layout. By stretching to it's constraints this new mode is not limited to the enclosing container but can be used for arbitrary areas of the screen. You could achieve this with other means before - but now we have a unified concept for everything, which sounds more logical to me. It's not that big a change, but a nice one nonetheless.

Guidelines are great additions

In addition to the layout and the editor we also have guidelines. These only make sense in the context of the ConstraintLayout - but they are actually proper views. They show up as separate view items in the hierarchy and get rendered at runtime.

But fear not. The decompiled Guildeline class is not only a mere 44 lines short - it also is as simple as a view can get. It doesn't draw anything, always sets the dimension to zero width and zero height in its onMeasure() method and on top of that sets itself to View.GONE in the constructors. So no problems here.

What this means is, that the guidelines can work as any other view, when it comes to constraints.

For the placement of the guidelines you can use fixed values (say always 100 dp from the left edge) or percent values (say always at 33% of the whole screen width).

Later on in this post I am going to show you a sample for how to make good use of guidelines.

Not as weird as Auto Layout

When I first heard about the new layout during the IO keynote, my first thought was: "Oh no! Auto Layout is coming". I have not done much with iOS, but what I have seen of Auto Layout, well, let's put it this way: I do not necessarily like it. It breaks to easily whenever you try to do something with the screen. It's only partially intuitive. In short it's nothing you like to work with.

Right now I do not have these negative thoughts when it comes to ConstraintLayout. Maybe Google learned something from what Apple did wrong. But it could as well be, that it's just because ConstraintLayout is not (yet?) as powerful as Auto Layout. I don't know - all I can say is, that ConstraintLayout seems to behave quite reasonably. But seasoned iOS devs might think about this issue very differently

What's to like about the new editor?

The new editor of course is also part of Google's plans to make life for us developers easier. Actually it might end up to be also quite useful for sketching and prototyping. Who knows.

I especially like these things:

• The properties pane has improved a lot
• The editor shows lint warnings and errors prominently
• The editor supports all kind of ViewGroups - not only ConstraintLayout
• Everything is still XML backed
• The screen is easily resizeable
• The editor lets you select an image for all ImageViews right away

The improved properties pane

Do you remember the old properties pane? All kind of attributes were listed in an alphabetical way. Only very few more important properties were at the top:

Now this has changed significantly - and it is much more usable that way:

Android Studio by default lists only important and often used properties in this pane. Though, if you feel like it, you can always go back to the old list by clicking on the "Show expert properties" button on the top right.

Some attributes probably should be added (like layout_weight for LinearLayout children or layout_gravity), but all in all this is much better than before.

Also note that for views that extend other views the properties pane lists the properties grouped by the class they originate from. In this case first those of Button and afterwards those of the inherited TextView.

The error hints

Another nice addition we haven't had before is the prominent display of lint errors and warnings in glaring red, so that you can't miss them:

And if you click on the number, it expands to show the problems:

And as you can see, it also shows the content of the view in question, so that you know right away which view has a problem. Nice!

The new editor supports all kind of ViewGroups

When Google introduced the new layout editor it only showed it with the ConstraintLayout. But you will be able to use it for all existing layouts as well. For Linearlayout this works well, for RelativeLayout not so much. For RelativeLayout some magic of the ConstraintLayout like dragging to which other view the new view should be relative to would make sense as well.

I guess Google puts more emphasis on correctly supporting ConstraintLayout than supporting the other layouts like RelativeLayout. Actually: I hope so. I very rarely used the designer with those older layouts. I preferred the XML view and expect this to remain unchanged for those. And for those "legacy" ViewGroup types I wouldn't mind if it stayed like that. After all the idea is to get rid of them anyway.

Everything is still XML backed

Obviously the aim of Google is for us to use the layout editor instead of the XML editor in the future. So why then is XML still a big deal?

In my opinion there are a few reasons:

• XML is better to fix fiddly things
  Sometimes working with a graphical editor has its drawbacks and it can become pretty difficult to access the correct handle and drag it onto the correct drop target. Or you made a mistake and marked some views as invisible or gone - or made them ridiculously small.
• XML is ideal for version control
  With a simple diff you can quickly see what changed over time. This is nice for yourself (using your local history or comparing changes to previous versions). But is even more important when collaborating with other. Code reviews and reasoning and discussing about pull requests is so much easier with XML and line numbers than having to throw screenshots around or having to run stuff just to understand even the simplest changes.

Easy resizability of screen

At the bottom right corner of the screen you have this handle. Nearly too unobstrusive:

You can use this handle to drag and resize the current preview screen and see which influence this has on your layout. Probably not often needed, but it can come in handy - while creating your layout, but also during presentations and trainings.

The editor lets you select an image for all ImageViews right away

Whenever you drag an ImageView or ImageButton onto the layout, the editor pops open a dialog in which you can choose the image to show or the color to use. That might not save that much work, but it's still a nice detail, that I appreciate:

Note that this screen also shows the more likely ones (the images of your project) at the top.

What about Performance?

Since performance improvements are among the main reasons to create this new layout, I did some performance tests to check if this goal is met.

I compared a layout used within a RecyclerView. Nothing too fancy, just some nested LinearLayout and RelativeLayout containers. I moved this layout manually over to ConstraintLayout and did some rather sloppy performance tests.

Comparing those two on an emulator as well as on an Nexus 5 yielded overall a performance penalty when using the new ConstraintLayout.

Performing worst is the measurement. The onMeasure() method takes roughly ten times as long as the one of the LinearLayout I used for comparison. And it uses up the bulk of the time with taking about 60 times as long as onLayout(). Thus the 30 per cent hit of the onLayout() method of ConstraintLayout compared to the one of the LinearLayout in question is nearly irrelevant. Finally layout inflation also took longer with ConstraintLayout than with LinearLayout.

The ConstraintLayout does lots of calculations to find out where and how to display each of its children. Internally (at least) three rather lengthy classes are working together to get the results: LinearSystem, ConstraintWidget and ConstraintWidgetContainer. To fully understand the performance behaviour I would have to dig into the depth of these classes (and for this I prefer the commented classes when their sources are released by Google). But just by having a cursory look at the decompiled code it looks like those classes have to do a lot.

Right now it looks like the performance improvements that Google hopes to achieve are far off. But at the Google IO talk John and Nicolas mentioned that they are working hard on improving the performance. So we can expect this to get better over time. And since the ConstraintLayout comes as a separate library, further improvements are likely even after the final release. If the result will be good enough in the end - well, that remains to be seen. We have to wait for future releases. And we have to do some more (and more thorough) testing with multiple layouts. Right now I'm more than willing to give Google the benefit of the doubt.

Additional note (as of July, 9th): This post was written based on the third alpha of ConstraintLayout. In the meantime a fourth has been released. Which, according to Nicolas Rouard, should be performing much better. I will give it a try and let you know about improvements in future posts. As I've written above: Google is hard at work on improving performance - and even this fourth release is still an alpha release!

Additional note (as of July, 22th): I have used the same layout for testing the fourth alpha build. It is indeed much better - but still needs improvements. With the performance imporvements of this build, onLayout() takes roughly a third of the time it took before. And onMeasure() now roughly twice as fast as before.

In one thread on twitter, Nicolas Rouard mentioned that - performancewise - ConstraintLayout is best for complex layouts for which you would have needed deeply nested layouts before. Keep this in mind, when deciding what layout to use. If time allows, I will try to find a suitable deeply nested layout to verify this in future add-ons to this post.

Some annoyances

Not all is working perfectly at the moment, though. Right now these things bother me the most:

• There's a noticeable lag between blueprint changes and design preview changes
• The preview is not always correct
• The blueprint view doesn't heed text layout constraints
• Constraints do not always work as expected
• Undo works very unreliably
• The editor undos stuff or changes stuff in unexpected ways

Noticable lag between blueprint changes and design preview changes

On bigger screens it's quite useful to open the blueprint view and the preview next to each other. But especially if you use lots of stretched views or many views that make use of the bias you will notice a growing lag in the preview.

This has already improved a bit with the latest updates, but is still noticeable and sometimes a bit irritating. Also while calculating those new positions the editor makes heavy use of your CPU. Luckily only for short bursts.

Preview is not always correct

When you miss some constraints, the preview view shows an incorrect screen. This actually is by design and has been different in the very first version of the layout editor. Back then (due to the aforementioned lag) things jumped around seemingly haphazardly, which of course was very disturbing. But apart from the lag the other reason for this was, that you can use the preview to drag things around. Which I strongly advocate against (see below). There's no reason for that. We have the blueprint editor to edit constraints. Let the preview do what its name implies.

Blueprint view doesn't heed text layout constraints

This is a fairly minor issue - yet one I would like to see corrected. In a TextView setting the gravity doesn't change the location of the text in the blueprint view. The setting is reflected correctly in the design preview, but when working with the blueprint only, it feels odd that changing this setting doesn't have any effect. Switching between the design and blueprint view just to verify that this setting did indeed work as expected is a bit cumbersome. Nothing that makes life really hard, but something that requires an extra step and makes one wonder at first.

Constraints do not always work as expected

The following screenshot admittedly show a very weird and pretty useless screen - but it shows that constraints might not work as you would expect them to work:

Never mind that this screen is among the weirdest app screen you might ever stumble upon. It still should be correct

As you can see the bottom button is left aligned to the right button in the second row. That's at least how the button should be. And you can also see, that this button is stretched. So why then does it stretch that far to the left? What makes this calculation go that wrong? My guess is, that the problem is not so much with the button at the bottom, but the buttons of the second row.

What worries me is not that this specific screen isn't working. The problem is, that I do not know why it's not working and what makes views appear so wrongly aligned. As long as things like this can happen, you are bound to run into this problem with a real screen on a real device eventually. And then it is really bothersome.

Undo works very unreliably

On one screen I accidentally moved one view around after I set some button's visibility to gone and to visible again. I hit Ctrl-Z and the button's visibility changes to gone again. What I had expected, of course, was to undo the last step - which was the accidental dragging of another view.

Trying to reproduce exactly these steps for this post I was not only not able to reproduce this particular problem. Instead I was now not able to undo the moving around step. Alas, very unpredictable again.

One of the earlier versions also behaved differently when using Undo via the menu or hitting Ctrl-Z. This appears to be fixed in the current version. But since Undo is so unreliable in general I do not know for sure.

I think this is the worst problems the editor has right now. When working graphically to quickly test stuff, moving items around should be easily - and reliably - reversible. Otherwise this editor hampers experimentation and is not useful for quickly sketching and for trying things out.

The editor undos or changes stuff in unexpected ways

This is even harder to describe properly since this seems to be even more haphazard than the undo issues. I do not have many proper examples.

On the screen I have worked with while checking and re-checking some stuff for this post I had a button. I changed the visibility to gone, then to invisible and then to visible. Afterwards the view was still drawn as if it were invisible. Reproducible: Of course not

The editor also tends to ignore size changes (or to revert them when switching between the the XML and then back to the design tab). But nothing of this is easy to pin down and reproducing these issues is unreliable as well I do not envy the Googlers having to fix these type of arbitrary issues. And I am sorry for not being able to be more specific. But whoever uses the editor will stumble upon the undo and unreliability issues pretty quickly.

Suggestions for additions

Currently I have two suggestions for the layout and three for the editor:

• Add width constraints based on other views
• Add an aspect-ratio constraint
• Add Ctrl-Mousewheel scrolling to the layout editor
• Allow changes in the blueprint view only
• Make the guideline's orientation indicator select the guideline

Of course there might be more suggestions in the future when I'm actually going to use ConstraintLayout for productive projects. But right now I think those additions would help a lot.

Now let me tell a bit about why I would like to see those items realized.

Add width and height constraints based on other views

For some screens I would like to ensure that neighbouring elements use the same width (or height) - but not a fixed width. For example you want buttons to divide up all of the width available. Or two images next to each other.

With LinearLayout you would simply set the layout's width to match_parent and then use layout_width="0" and layout_weight="1" on its children and they would divide up the available space.

When I first experimented with ConstraintLayout I thought, that would be easy. Simply use three buttons next to each other, align each of the right ones to the one left of it and finally the left button to the left edge of the screen and the right one to the right edge of the screen. And then make all of them stretch. But this didn't work as expected:

What you see here is that the first two are as they would be with a width of wrap_content and only the last one is actually stretched. In a bug report I filed, a Googler remarked that this works as designed. Stretch doesn't divide up the remaining space between all stretching views. Keep this in mind!

But not all is lost: The team plans to add some constraints that would allow us to do this in the future. Meaning after the first release of ConstraintLayout. The bad part is, that we do not have this right away. The good part is, that they have much more plans for this layout and that we can expect it to get better over time.

Guidelines to the rescue

But even with the first release not having width constraints, we might be able to achieve this, depending on the specific layout at hand.

For the layout shown above the solution is to use Guildeline objects to divide up the space and then align the buttons to it. Here's what the workaround looks like (click on the image to see its original size):

And since sometimes code is easier to understand, you can find the code for this layout in this gist. The gist contains the correctly sized buttons as well as the first attempt without guidelines.

Romain Guy pointed out in the comments that the ConstraintLayout indeed has this feature. I'm going to add some more information about how to use it soon. Stay tuned!

Even though I never published it, I once made a board game. For things like this it would be nice to have the ability to ensure that this view always has the same height as it's width. And I can also imagine other use cases where elements should use a certain height depending on the device width. Say half the height as the view's width.

Whatever one might think of Auto Layout, there's a reason Apple provides it there.

Make the guideline's orientation indicator select the guideline

If you add guidelines they get an indicator at the top (or on the left for horizontal guidelines) which show whether a guideline is positioned at a fixed margin or at a percentage of the total width. Here's the indicator for a percentage:

It would feel more natural if I could select the guideline by clicking on this indicator. Right now I first have to select the guideline by clicking somewhere on the line itself. Afterwards I can use the indicator to drag the guideline around or to change the type of indicator. Why not directly so?

Add Ctrl + Mouse Wheel scrolling to the layout editor

The layout editor can get very crowded - depending on the amount of views, how close they are and how they are constrained. In some cases it would be convenient to quickly zoom into the screen, do some designing, and then quickly zoom out again. It also would be really helpful while presenting about the editor and the ConstraintLayout

This is what we're used to when using graphics software. And Android Studio has a setting to allow this way of zooming for text:

Thus I would like to see, the zooming to work for the layout editor whenever this setting is checked in Android Studio.

Allow changes to be made in the blueprint view only

Currently it's possible to change layout settings in the blueprint view - but also in the preview view. I think the latter should not be possible at all. Restrict designing to the blueprint. If you do so, the preview would be less cluttered - and also might perform better.

The most important reason in my opinion though is, that we are then free to actually use the preview as it should be: A realistic preview. I have already mentioned that the preview is not correct in all cases. And this has to do with the fact that you should be able to drag views around there as well. But if we drop the need for this, we actually can see problems like missing constraints right away.

What about LinearConstraintLayout and TableConstraintLayout

I just had a cursory look at both. Thus I do not have an opinion on them. Maybe in some later post. Depends on how they turn out.

One thing is worth mentioning, though: Those two layouts exist, but Google doesn't explain them at all. I think they didn't even mention them during their IO talk. So that's the one thing I can say: Please let us know what you intend to do with these ConstraintLayout children and what they should be useful for. I actually have a hard time seeing much use of LinearConstraintLayout for example - but hopefully Google proves me wrong.

Does Anko support ConstraintLayout?

For those that use Kotlin and like to use Anko as an alternative to XML, the answer right now is: No! Anko doesn't support ConstraintLayout.

Yan Zhulanow opened issue #210 within the Anko project to add support for ConstraintLayout to Anko. Right now, no further comments have been added. But most likely this will be fixed soon.

To sum things up

The new layout and the new layout editor both show promise. They are currently in alpha (the layout) or preview (the editor), so we can expect to see many - if not all - of the problems ironed out until the final release of both of them.

It's definitely worth getting yourself accustomed with the new layout. I'm quite confident that it is the future.

Having said that, I currently don't use the ConstraintLayout for real projects. But I expect to be able to do so pretty soon.

Please note that everything I have written here is based on what I currently think about the ConstraintLayout and the design editor. There have been lots of improvements during the last iterations of both the ConstraintLayout and the editor and I expect this to go on.

Also keep in mind, that we are only starting to understand the possibilities of ConstraintLayout! The more we use it the more we will know how to do stuff. I'm actually quite excited about it - despite some of the problems the alpha still has.

I very much appreciate what the Googlers are doing there! Keep up the good work - and thanks!

The post Some Thoughts on Android’s new ConstraintLayout and Android Studio’s new Design Editor appeared first on Grokking Android.

But there are other methods, that do not change the stream of items in any way - I call those methods side effect methods.

What do I mean by side effect methods?

Side effect methods do not affect your stream in itself. Instead they are invoked when certain events occur to allow you to react to those events.

For example: if you're interested in doing something outside of your Subscriber's callbacks whenever some error occurs, you would use the doOnError() method and pass to it the functional interface to be used whenever an error occurs:

someObservable
      .doOnError(new Action1() {
         @Override
         public void call(Throwable t) {
            // use this callback to clean up resources,
            // log the event or or report the 
            // problem to the user
         }
      })
      //...

The most important part is the call() method. The code of this method will be executed before the Subscriber's onError() method is called.

In addition to exceptions RxJava offers many more events to which you can react:

The <T> refers either to the type of the item emitted or, in the case of the onError() method, the type of the Throwable thrown.

The functional interfaces are all of type Action0 or Action1. This means that the single methods of these interfaces do not return anything and take either zero arguments or one argument, depending on the specific event.

Since those methods do not return anything, they cannot be used to change the emitted items and thus do not change the stream of items in any way. Instead these methods are intended to cause side effects like writing something on disk, cleaning up state or anything else that manipulates the state of the system itself instead of the stream of events.

Note: The side effect methods themselves (doOnNext(), doOnCompleted() and so on) do return an Observable. That's to keep the interface fluent. But the returned Observable is of the same type and emits the same items as the source Observable.

What are they useful for?

Now since they do not change the stream of items there must be other uses for them. I present here three examples of what you can achieve using these methods:

• Use doOnNext() for debugging
• Use doOnError() within flatMap() for error handling
• Use doOnNext() to save/cache network results

So let's see these examples in detail.

Use doOnNext() for debugging

With RxJava you sometimes wonder why your Observable isn't working as expected. Especially when you are just starting out. Since you use a fluent API to transform some source into something that you want to subscribe to, you only see what you get at the end of this transformation pipeline.

When I was learning about RxJava I had some initial experience with Java's Streams. Basically you have the same problem there. You have a fluid API to move from one Stream of some type to another Stream of another type. But what if it doesn't work as expected?

With Java 8 Streams you have the peek() method. So when starting out with RxJava I wondered if something comparable is available. Well, there is. Actually, RxJava offers much more!

You can use the doOnNext() method anywhere in your processing pipeline to see what is happening and what the intermediary result is.

Here's an example of this:

Observable someObservable = Observable
            .from(Arrays.asList(new Integer[]{2, 3, 5, 7, 11}))
            .doOnNext(System.out::println)
            .filter(prime -> prime % 2 != 0)
            .doOnNext(System.out::println)
            .count()
            .doOnNext(System.out::println)
            .map(number -> String.format("Contains %d elements", number));

Subscription subscription = o.subscribe(
            System.out::println,
            System.out::println,
            () -> System.out.println("Completed!"));

And here is the output of that code:

2
3
3
5
5
7
7
11
11
4
Contains 4 elements
Completed!

That way you can glean valuable information about what is going on when your Observable doesn't behave as you expected.

The doOnError() and doOnCompleted() methods can also be useful for debugging the state of your pipeline.

Note: If you're using RxJava while developing for Android please have a look at the Frodo and Fernando Ceja's post explaining about the motivation for and usage of Frodo. With Frodo you can use annotations to debug your Observables and Subscribers.

The shown way of using doOnNext() and doOnError() does not change much of the system state - apart from bloating your log and slowing everything down.

But there are other uses for these operators. And in those cases you use those methods to actually change the state of your system. Let’s have a look at them.

Use doOnError() within flatMap()

Say you're using Retrofit to access some resource over the network. Since Retrofit supports observables, you can easily use those calls within your processing chain using flatMap().

Alas, network related calls can go wrong in many ways - especially on mobiles. In this case you might not want the Observable to stop working, which it would if you were to rely on your subscriber's onError() callback alone.

But keep in mind that you have an Observable within your flatMap() method. Thus you could use the doOnError() method to change the UI in some way, yet still have a working Observable stream for future events.

So what this looks like is this:

flatMap(id -> service.getPost()
       .doOnError(t -> {
          // report problem to UI
       })
       .onErrorResumeNext(Observable.empty())
)

This method is especially useful if you query your remote resource as a result of potentially recurring UI events.

Use doOnNext() to save/cache network results

If at some point in your chain you make network calls, you could use doOnNext() to store the incoming results to your local database or put them in some cache.

It would be as simple as the following lines:

// getOrderById is getting a fresh order 
// from the net and returns an observable of orders
// Observable<Order> getOrderById(long id) {...}

Observable.from(aListWithIds)
         .flatMap(id -> getOrderById(id)
                              .doOnNext(order -> cacheOrder(order))
         // carry on with more processing

See this pattern applied in more detail in Daniel Lew's excellent blog post about accessing multiple sources.

Wrap up

As you've seen, you can use the side effect methods of RxJava in multiple ways. Even though they do not change the stream of emitted items, they change the state of your overall system. This can be something as simple as logging the current items of your Observable at a certain point within your processing pipeline, up to writing objects to your database as a result of a network call.

In my next post I am going to show you how to use RxJava's hooks to get further insights. Stay tuned!

The post RxJava’s Side Effect Methods appeared first on Grokking Android.

A look at the Observable class might make you dizzy. Looking at the source even more so. Not only does this beast consist of nearly 10.000 lines (though, 7600 lines of that are comments) but it also consists of a bunch of final methods. Actually only final methods! 330 of them! But you can inherit from Observable. Odd, very odd!

Next you might think: Ah never mind, let me just inherit from Observable and see how far I get.

But should you bother to look at the documentation of the constructor, you see this:

Note: Use create(OnSubscribe) to create an Observable, instead of this constructor,
unless you specifically have a need for inheritance.

Okay, since you are eager to know what this is all about: you have a short look at the documentation of onCreate():

Returns an Observable that will execute the specified function when a Subscriber subscribes to
it.
...
Write the function you pass to create so that it behaves as an Observable: It should invoke the
Subscriber's onNext, onError, and onCompleted methods appropriately.
...
A well-formed Observable must invoke either the Subscriber's onCompleted method exactly once or
its onError method exactly once.

Hm... Maybe a look at this method’s code might help?

public final static  Observable create(OnSubscribe f) {
   return new Observable(hook.onCreate(f));
}

What? It's just passing this stuff to the constructor anyway? So what's it with this warning?

Well, first: Why would you want to inherit Observable in the first place? All methods of it are final. You basically cannot add much functionality to Observable by inheritance because of this. It's better to stick to the RxJava way to do things: And that is by chaining API calls of its fluent API.

Another thing is, that it's not as explicit. Using the create() method you directly see what the created Observable is up to.

Furthermore: If you look more closely at the source snippet, you will notice this tiny little hook.onCreate() call. That's actually quite important. Because RxJava allows you to supply hooks that wrap certain method calls and allow you to substitute certain aspects of how RxJava behaves.

I for one use this hook in debug mode to log which thread my observables get created on and on what threads operators are lifted. In server environments you might want to add monitoring logic to your hooks. By using the constructor, you bypass this and rob yourself of the possibility to do so easily.

Having said all this: It's not forbidden to inherit from Observable. As with all rules, there are situations where they do not apply and where inheritance does make sense. The Subject class for example does inherit from Observable. Just be careful and try to think twice when doing so 

The post Why use Observable.create() and not just inherit from Observable? appeared first on Grokking Android.

Well, I think using them for selection is not the right way to go. Instead, I think that you should stick with StateListDrawables and the activated state.

The use case of the sample

In this sample the user can select multiple items that are shown in purple. The first item gets selected using a long click. Any subsequent click will select or deselect items. Users can also deselect items, that were previously selected, with a single click. The user can then use a bulk delete operation on all selected items. The user should be able to see the number of currently selected items.

Obviously that sounds a lot like a contextual action bar (CAB), which is what I used. BTW: As you can see in the screenshot, the CAB doesn't look like I expected it to look. It should use my android:colorPrimaryDark for the contextual app bar (Material lingo). But either the theming guide for material design is not correct, or maybe it's the current L preview, or - more likely - it's my code. Any takers? Please let me know, if you know what's wrong here. Thanks!

Here's a screenshot of the final result. You can also find a video near the end of this post.

Overview

The solution that I suggest is Adapter-based. As you might recall from my last post, RecyclerView doesn't care about the visual representation of individual items. Thus I quickly ruled out to subclass RecyclerView.

RecyclerView doesn't itself need to know about the set of items nor about the state these items are in. In this way my proposed solution differs from the way you did selections with ListView or GridView in the past. There you checked items directly using the setItemChecked() method and you set the kind of selection mode with setChoiceMode().

With RecyclerView any information about the data set belongs to your RecyclerView.Adapter subclass. Thus anything required to show the selection state of items should also be in your RecyclerView.Adapter subclass.

The adapter not only stores information about the state of each item, but it also creates the views for each items. That's why I use the adapter for setting the activated state.

Methods for setting the selected state

Based on this use case, I chose to add the following methods to my RecyclerView.Adapter subclass:

• void toggleSelection(int pos)
• void clearSelections()
• int getSelectedItemCount()
• List<Integer> getSelectedItems()

With toggleSelection() an item changes its selection state. If it was previously selected it gets deselected, and vice versa.

You can always clear all selections with clearSelections(). You shouldn't forget to do that when you finish the action mode.

The other methods get the number of currently selected items and all positions of the currently selected items.

Necessary changes to the adapter

Here's the relevant part of my Adapter:

public class RecyclerViewDemoAdapter
        extends RecyclerView.Adapter
                <RecyclerViewDemoAdapter.ListItemViewHolder> {

   // ...
   private SparseBooleanArray selectedItems;
   
   // ...

   public void toggleSelection(int pos) {
      if (selectedItems.get(pos, false)) {
         selectedItems.delete(pos);
      }
      else {
         selectedItems.put(pos, true);
      }
      notifyItemChanged(pos);
   }
   
   public void clearSelections() {
      selectedItems.clear();
      notifyDataSetChanged();
   }
   
   public int getSelectedItemCount() {
      return selectedItems.size();
   }
   
   public List<Integer> getSelectedItems() {
      List<Integer> items = 
            new ArrayList<Integer>(selectedItems.size());
      for (int i = 0; i < selectedItems.size(); i++) {
         items.add(selectedItems.keyAt(i));
      }
      return items;
   }

   // ...

}

Notice how I used notifyDataSetChanged() and notifyItemChanged(). That's necessary because I do not have access to the View object itself and thus cannot set the activated state directly. Instead I have to tell Android to ask the Adapter for a new ViewHolder binding.

How to use those methods from within the Activity

If you have used ListViews with the Contextual ActionBar in the past, you know that for selecting multiple items you had to set the choice mode to CHOICE_MODE_MULTIPLE_MODAL and implement the AbsListview.MultiChoiceModeListener interface to achieve the desired result. See this guide on Android's developer site for more details. Now since RecyclerView doesn't offer this interface (and rightly so), you have to find a way around this.

My solution is to use the GestureDetector to detect long presses. You can find this code at the end of the Activity. In the long-press callback, I create the actionmode, detect which view was pressed and call toggleSelection() on the adapter.

public void onLongPress(MotionEvent e) {
   View view = 
      recyclerView.findChildViewUnder(e.getX(), e.getY());
   if (actionMode != null) {
      return;
   }
   actionMode = 
      startActionMode(RecyclerViewDemoActivity.this);
   int idx = recyclerView.getChildPosition(view);
   myToggleSelection(idx);
   super.onLongPress(e);
}

private void myToggleSelection(int idx) {
   adapter.toggleSelection(idx);
   String title = getString(
         R.string.selected_count, 
         adapter.getSelectedItemCount());
   actionMode.setTitle(title);
}

For the actionmode to work, the activity has to implement the ActionMode.Callback interface. I won't go into this. It's described in detail in the official menu guide on the Android site.

To understand of how selections work only two of this interface's methods are interesting:

• onActionItemClicked()

  Android calls this method when the user presses the delete icon. In this method I get the list of selected items from the adapter and call the removeData() method of the adapter for each item - so that Android can smoothly animate them - as shown in the previous post. And, of course, I have to finish the action mode afterwards.

• onDestroyActionMode()

  Android calls this method when it's leaving actionmode prior to showing the normal ActionBar (app bar) again. This happens either when the user selects the check mark or when he/she selects the delete icon.

Here's the code for these two methods:

@Override
public boolean onActionItemClicked(
         ActionMode actionMode, 
         MenuItem menuItem) {
   switch (menuItem.getItemId()) {
      case R.id.menu_delete:
         List<Integer> selectedItemPositions = 
               adapter.getSelectedItems();
         for (int i = selectedItemPositions.size() - 1; 
               i >= 0; 
               i--) {
            adapter.removeData(selectedItemPositions.get(i));
         }
         actionMode.finish();
         return true;
      default:
         return false;
   }
}

@Override
public void onDestroyActionMode(ActionMode actionMode) {
   this.actionMode = null;
   adapter.clearSelections();
}

The StateListDrawable XML file

So far I have shown you how to select items and set the activated state. To finally highlight those items I use StateListDrawables.

A StateListDrawable is a drawable that changes its content based on the state of the view. You can define those in XML files. The first matching entry for a given state determines which drawable Android uses. Since I only care about the activated state the XML file is actually very simple:

<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android=
      "http://schemas.android.com/apk/res/android">
   <item android:state_activated="true" 
         android:drawable="@color/primary_dark" />
   <item android:drawable="@android:color/transparent" />
</selector>

And of course you have to use this StateListDrawable somewhere. I use it as the background for each item:

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/container_list_item"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@drawable/statelist_item_background">
    <include layout="@layout/common_item_layout" />
</RelativeLayout>

The following video shows the result of this post's changes:

A short video showing the Contextual ActionBar and the selection of items

Sample project

You can download the sample from my github page. I have tagged the revision of last week's post with "simpleSample" while the revision for this week uses the tag "selectionSample".

Feel free to submit pull requests if you have suggestions on how to improve the code.

And that's it for today

This was a short example of how to make use of the RecyclerView.Adapter and how to benefit from those abstractions. I guess I won't go into much more detail about the adapter in future posts. But I recommend that you take a look at Gabriele Mariotti's great example of how to use an RecyclerView.Adapter with sectioned lists.

I hope this post helps you in your work with RecyclerView.Adapters. Selection is just one of the many things an adapter is useful for. If you have a look at Gabriele's gist, you can see how to use your adapter to support different view types. Just keep in mind the separation of concerns and don't mix responsibilities.

The post Selecting Items of a RecyclerView using StateListDrawables appeared first on Grokking Android.

Part of this preview are two new views: RecyclerView and CardView. This post gives you an introduction to the RecyclerView, it's many internal classes and interfaces, how they interact and how you can use them.

Let me start with the good news: RecyclerView is part of the support library. So you can use it right now. Ok: You can use it as soon as the final support lib accompanying the L release gets released. So better to familiarize yourself with it right away

Sample project

The screenshots and the video at the end of the post show the sample project for this post in action. You can find the source of this sample at github. Keep in mind that the RecyclerView API is not yet finalized. Google might still change things that could break the sample when they release the final version of Android L.

What's with this odd name? Why RecyclerView?

This is how Google describes RecyclerView in the API documentation of the L preview release:

A flexible view for providing a limited window into a large data set.

So RecyclerView is the appropriate view to use when you have multiple items of the same type and it's very likely that your user's device cannot present all of those items at once. Possible examples are contacts, customers, audio files and so on. The user has to scroll up and down to see more items and that's when the recycling and reuse comes into play. As soon as a user scrolls a currently visible item out of view, this item's view can be recycled and reused whenever a new item comes into view.

The following screenshots of the sample app illustrate this. On the left is the sample app after the initial start. When you scroll the view up, some views become eligible for recycling. The red area on the right screenshot, for example, highlights two invisible views. The recycler can now put these views into a list of candidates to be reused should a new view be necessary.

Recycling of views is a very useful approach. It saves CPU resources in that you do not have to inflate new views all the time and it saves memory in that it doesn't keep plenty of invisible views around.

Now, you might say: That's nothing new. And you're right! We had that with ListView for a very long time. The concept of recycling views itself it not new. But while you previously had a ListView where the appearance, recycling and everything was tightly coupled, Google now follows a much better, a much more flexible approach with the new RecyclerView. I really like the approach Google has taken here!

RecyclerView doesn't care about visuals

Here's the thing: While with Listview we had tight coupling, Google now uses an approach where the RecyclerView itself doesn't care about visuals at all. It doesn't care about placing the elements at the right place, it doesn't care about separating any items and not about the look of each individual item either. To exaggerate a bit: All RecyclerView does, is recycle stuff. Hence the name.

Anything that has to do with layout, drawing and so on, that is anything that has to do with how your data set is presented, is delegated to pluggable classes. That makes the new RecyclerView API extremely flexible. You want another layout? Plug in another LayoutManager. You want different animations? Plug in an ItemAnimator. And so on.

Here's the list of the most important classes that RecyclerView makes use of to present the data. All these classes are inner classes of the RecyclerView:

In the next paragraphs I will briefly describe what each class or interface is about and how RecyclerView uses it. In future posts I will revisit some of these classes, write about them in detail and show you how to customize them for your project's needs.

ViewHolder

ViewHolders are basically caches of your View objects. The Android team has been recommending using the ViewHolder pattern for a very long time, but they never actually enforced the use of it. Now with the new Adapter you finally have to use this pattern.

It's a bit weird that Google waited so long to enforce the usage of the ViewHolder pattern, but better late than never. If you do not know about the ViewHolder pattern, have a look at this Android training session. It uses the old Adapter, but the pattern itself hasn't changed.

Also searching for ViewHolder should yield plenty of hits to further blog posts. For example this post by Antoine Merle about ListView optimizations.

One thing that is specific to any RecyclerView.ViewHolder subclass is that you can always access the root view of your ViewHolder by accessing the public member itemView. So there's no need to store that within your ViewHolder subclass.

And should you decide to override toString() have a look at the base class. Its toString() implementation prints some useful information you should consider to use for your log messages as well.

Here's the code for the ViewHolder of the sample project. The ViewHolder is an inner class of the sample project's Adapter:

public final static class ListItemViewHolder extends RecyclerView.ViewHolder {
   TextView label;
   TextView dateTime;
   
   public ListItemViewHolder(View itemView) {
      super(itemView);
      label = (TextView) itemView.findViewById(R.id.txt_label_item);
      dateTime = (TextView) itemView.findViewById(R.id.txt_date_time);
   }
}

RecyclerView.Adapter

Adapters fulfill two roles: They provide access to the underlying data set and they are responsible for creating the correct layout for individual items. Adapters always were part of Android and were used in many places. ListView, AutoCompleteTextView, Spinner and more all made use of adapters. All those classes inherit from AdapterView. But not so RecyclerView.

For the new RecyclerView Google has decided to replace the old Adapter interface with a new RecyclerView.Adapter base class. So say good bye to things like SimpleCursorAdapter, ArrayAdapter and the like. At least in their current incarnation.

Currently there is no default implementation of RecyclerView.Adapter available. Google might add some later on, but I wouldn't bet on this. For Animations to work properly, cursors and arrays aren't the best fit, so porting the current Adapter implementations might not make too much sense.

Since RecyclerView.Adapter is abstract you will have to implement these three methods:

• public VH onCreateViewHolder(ViewGroup parent, int viewType)
• public void onBindViewHolder(VH holder, int position)
• public int getItemCount()

The VH in the method signatures above is the generic type parameter. You specify the concrete type to use when you subclass the RecyclerView.Adapter. You can see this in line 3 of the next code sample.

The most basic adapter for the sample layout looks like this:

public class RecyclerViewDemoAdapter extends 
        RecyclerView.Adapter
        <RecyclerViewDemoAdapter.ListItemViewHolder> {

    private List<DemoModel> items;

    RecyclerViewDemoAdapter(List<DemoModel> modelData) {
        if (modelData == null) {
            throw new IllegalArgumentException(
                  "modelData must not be null");
        }
        this.items = modelData;
    }

    @Override
    public ListItemViewHolder onCreateViewHolder(
            ViewGroup viewGroup, int viewType) {
        View itemView = LayoutInflater.
                from(viewGroup.getContext()).
                inflate(R.layout.item_demo_01, 
                        viewGroup,
                        false);
        return new ListItemViewHolder(itemView);
    }

    @Override
    public void onBindViewHolder(
            ListItemViewHolder viewHolder, int position) {
        DemoModel model = items.get(position);
        viewHolder.label.setText(model.label);
        String dateStr = DateUtils.formatDateTime(
                viewHolder.label.getContext(),
                model.dateTime.getTime(),
                DateUtils.FORMAT_ABBREV_ALL);
        viewHolder.dateTime.setText(dateStr);
    }

    @Override
    public int getItemCount() {
        return items.size();
    }

    public final static class ListItemViewHolder 
           extends RecyclerView.ViewHolder {
        // ... shown above in the ViewHolder section
    }
}

RecyclerView.LayoutManager

The LayoutManager is probably the most interesting part of the RecyclerView. This class is responsible for the layout of all child views. There is one default implementation available: LinearLayoutManager which you can use for vertical as well as horizontal lists.

You have to set a LayoutManager for your RecyclerView otherwise you will see an exception at Runtime:

08-01 05:00:00.000  2453  2453 E AndroidRuntime: java.lang.NullPointerException: Attempt to invoke virtual method 'void android.support.v7.widget.RecyclerView$LayoutManager.onMeasure(android.support.v7.widget.RecyclerView$Recycler, android.support.v7.widget.RecyclerView$State, int, int)' on a null object reference
08-01 05:00:00.000  2453  2453 E AndroidRuntime: 	at android.support.v7.widget.RecyclerView.onMeasure(RecyclerView.java:1310)

Only one method of LayoutManager is currently abstract:

• public LayoutParams generateDefaultLayoutParams()

But there is another one where the code states that you should overrride it since it's soon going to be abstract:

public void scrollToPosition(int position) {
   if (DEBUG) {
      Log.e(TAG, "You MUST implement scrollToPosition. It will soon become abstract");
   }
}

That's very weird! Why not make it abstract right away? Anyway: Better you override this one to be on the safe side for when Google releases the final version of L.

But only overriding those two methods won't get you very far. After all the LayoutManager is responsible for positioning the items you want to display. Thus you have to override onLayoutChildren() as well.

This method also contains a log statement stating "You must override onLayoutChildren(Recycler recycler, State state)". Ok, then make it abstract Luckily there's still plenty (?) of time to change that into a proper abstract method for the final release of L. We all make mistakes. After all, my "Stupid stuff devs make" series is all about blunders that I made. So don't get me wrong. No hard feelings here!

LinearlayoutManager

The LinearLayoutManager is currently the only default implementation of LayoutManager. You can use this class to create either vertical or horizontal lists.

The implementation of LinearLayoutManager is rather complex and I only had a look at some key aspects. I will return to this implementation in my post about custom LayoutManagers.

To use the LinearLayoutManager you simply have to instantiate it, tell it which orientation to use and you are done:

LinearLayoutManager layoutManager = new LinearLayoutManager(context);
layoutManager.setOrientation(LinearLayoutManager.VERTICAL);
layoutManager.scrollToPosition(currPos);
recyclerView.setLayoutManager(layoutManager);

LinearLayoutManager also offers some methods to find out about the first and last items currently on screen:

• findFirstVisibleItemPosition()
• findFirstCompletelyVisibleItemPosition()
• findLastVisibleItemPosition()
• findLastCompletelyVisibleItemPosition()

Surprisingly these methods are not part of the source code in the SDK folder, but you can use them as they are part of the binaries. As I cannot imagine those being removed, I'm sure you'll find these in the final L release as well.

Other methods help you get the orientation of the layout or the current scroll state. Others will compute the scroll offset. And finally you can reverse the ordering of the items.

Since I'm going to write an extra post about LayoutManagers this should suffice for now.

RecyclerView.ItemDecoration

With an ItemDecoration you can add an offset to each item and modify the item so that items are separated from each other, highlighted or, well, decorated.

You do not have to use an ItemDecoration. If, for example, you use a CardView for each item, there's no need for an ItemDecoration.

On the other hand you can add as many ItemDecorations as you like. The RecyclerView simply iterates over all ItemDecorations and calls the respective drawing methods for each of them in the order of the decoration chain.

The abstract base class contains these three methods:

• public void onDraw(Canvas c, RecyclerView parent)
• public void onDrawOver(Canvas c, RecyclerView parent)
• public void getItemOffsets(Rect outRect, int itemPosition, RecyclerView parent)

Anything you paint in onDraw() might be hidden by the content of the item views but anything that you paint in onDrawOver() is drawn on top of the items. If you simply create a bigger offset and, for example, use this offset to paint dividers, this of course is of no importance. But if you really want to add decorations, you have to use onDrawOver().

The LayoutManager calls the getItemOffset() method during the measurement phase to calculate the correct size of each item's views. The outRect parameter might look a bit odd at first. Why not use a return value instead? But it really makes a lot of sense, since this allows RecyclerView to reuse one Rect object for all children and thus save resources. Not necessarily nice — but efficient.

One thing I didn't expect considering the name of the class is that the onDraw()/onDrawOver() methods are not called for each item, but just once for every draw operation of the RecyclerView. You have to iterate over all child views of the RecyclerView yourself.

I will explain this in more detail in a follow-up post about writing your own ItemDecorations.

RecyclerView.ItemAnimator

The ItemAnimator class helps the RecyclerView with animating individual items. ItemAnimators deal with three events:

• An item gets added to the data set
• An item gets removed from the data set
• An item moves as a result of one or more of the previous two operations

Luckily there exists a default implementation aptly named DefaultItemAnimator. If you do not set a custom ItemAnimator, RecyclerView uses an instance of DefaultItemAnimator.

Obviously for animations to work, Android needs to know about changes to the dataset. For this Android needs the support of your adapter. In earlier versions of Android you would call notifyDataSetChanged() whenever changes occured, this is no longer appropriate. This method triggers a complete redraw of all (visible) children at once without any animation. To see animations you have to use more specific methods.

The RecyclerView.Adapter class contains plenty of notifyXyz() methods. The two most specific are:

• public final void notifyItemInserted(int position)
• public final void notifyItemRemoved(int position)

The following video shows the result of an addition as well as a removal of an item in the sample app:

A short video showing the default animations for the removal and addition of elements

Listeners

RecyclerView also offers some rather generic listeners. Once again you can safely forget everything you used to use up to now. There is no OnItemClickListener or OnItemLongClickListener. But you can use an RecyclerView.OnItemTouchListener in combination with gesture detection to identify those events. A bit more work and more code to achieve the same result. I still hope for Google to add those Listeners in the final release. But whether those Listeners will be added is as an open question.

Combining all classes

You combine the classes either in a fragment or an activity. For the sake of simplicity my sample app uses activities only.

First of all here's the layout file containing the RecyclerView:

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingTop="@dimen/activity_vertical_margin"
    android:paddingBottom="@dimen/activity_vertical_margin"
    tools:context=".RecyclerViewDemoActivity">

    <android.support.v7.widget.RecyclerView
        android:id="@+id/recyclerView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context=".MainActivity"
        tools:listitem="@layout/item_demo_01"
        />

    <ImageButton
        android:id="@+id/fab_add"
        android:layout_alignParentRight="true"
        android:layout_alignParentBottom="true"
        android:layout_width="@dimen/fab_size"
        android:layout_height="@dimen/fab_size"
        android:layout_gravity="bottom|right"
        android:layout_marginRight="16dp"
        android:layout_marginBottom="16dp"
        android:background="@drawable/ripple"
        android:stateListAnimator="@anim/anim"
        android:src="@drawable/ic_action_add"
        android:elevation="1dp"
        />
</RelativeLayout>

As you can see, nothing special here. You do not define the orientation or stuff like that on the RecyclerView. Actually RecyclerView itself makes no use of the attributes, it passes them on to the parent (which is ViewGroup) and that's it.

There is one place within RecyclerView where an AttributeSet is used and that is in the generateLayoutParams() method:

@Override
public ViewGroup.LayoutParams generateLayoutParams(AttributeSet attrs) {
   if (mLayout == null) {
      throw new IllegalStateException("RecyclerView has no LayoutManager");
   }
   return mLayout.generateLayoutParams(getContext(), attrs);
}

In this snippet the RecyclerView passes the AttributeSet on to the LayoutManager.

The Java code is also pretty simple:

setContentView(R.layout.activity_recyclerview_demo);
recyclerView = (RecyclerView) findViewById(R.id.recyclerView);

LinearLayoutManager layoutManager = new LinearLayoutManager(this);
layoutManager.setOrientation(LinearLayoutManager.VERTICAL);
layoutManager.scrollToPosition(0);
recyclerView.setLayoutManager(layoutManager);

// allows for optimizations if all item views are of the same size:
recyclerView.setHasFixedSize(true);

// For the sake of simplicity I misused the Application subclass as a DAO
List<DemoModel> items = RecyclerViewDemoApp.getDemoData();
adapter = new RecyclerViewDemoAdapter(items);
recyclerView.setAdapter(adapter);

RecyclerView.ItemDecoration itemDecoration =
        new DividerItemDecoration(this, DividerItemDecoration.VERTICAL_LIST);
recyclerView.addItemDecoration(itemDecoration);

// this is the default; 
// this call is actually only necessary with custom ItemAnimators
recyclerView.setItemAnimator(new DefaultItemAnimator());

// onClickDetection is done in this Activity's OnItemTouchListener
// with the help of a GestureDetector;
// Tip by Ian Lake on G+ in a comment to this post:
// https://plus.google.com/+LucasRocha/posts/37U8GWtYxDE
recyclerView.addOnItemTouchListener(this);
gesturedetector =
        new GestureDetectorCompat(this, new RecyclerViewDemoOnGestureListener());

Connecting all those elements together roughly consists of these steps:

1. Get a reference to your RecyclerView
2. Create a LayoutManager and add it
3. Create an Adapter and add it
4. Create zero or more ItemDecorations as needed and add them
5. Create an ItemAnimator if needed and add it
6. Create zero or more listeners as needed and add them

All in all about 30 lines of code.

Now of course this is misleading. That's only the glue code. The really interesting stuff is in RecyclerView's many inner classes which you can subclass and tweak to your needs. That's where the real work is done.

But the separation of concerns Google created helps you stick to one task within one implementation and it should make reuse easier to achieve. That's why I like RecyclerView and its ecosystem. I'm not afraid to criticize big G, but that's well done, Google!

Gradle integration

To use RecyclerView you have to add it to your gradle file. Adding the support library alone is not enough:

dependencies {
   //...
   compile 'com.android.support:recyclerview-v7:+'
   //...
}

Is that the final API?

Of course I do not know if the concrete implementations that the preview contains will be in the final release of Android L. But I guess so. And I expect some additions as well as minor changes to the API, based on bug reports and developer feedback.

Google itself gives one hint in the current API documentation about more stuff to come. The documentation for the RecyclerView.LayoutManager class contains this nugget:

Several stock layout managers are provided for general use.

So we can expect more LayoutManagers. Which, of course, is good. Furthermore I expect at least one default ItemDecoration as well. After all the support library's sample project contains a DividerItemDecoration, which works well with the LinearLayoutManager.

I'm more skeptical about adapters. While an ArrayAdapter (or better yet, ListAdapter) is very well possible, I am more doubtful about a CursorAdapter since cursors do not lend themself easily to the new addition and removal notifications within the Adapter.

Lucas Rocha's TwoWayView to simplify your life

I strongly recommend to have a look at Lucas Rocha's TwoWayView project. He has updated his project to work with RecyclerView and has done a great deal to make using RecyclerView a lot easier. For many use cases the default layouts he provides should suffice. And he also provides support for custom LayoutManagers. Which are simpler to write using his framework than with the base RecyclerView.

Take a look at his project and check out if it covers all you need. Using it helps you get rid of some of RecyclerView's complexity.

For more information about his project see his blog post about how TwoWayView extends and simplifies RecyclerView.

To learn about news about this project follow Lucas Rocha on Google plus or Twitter.

I will cover TwoWayView in this series as well - so stay tuned

Report bugs!

We currently have a developer preview. The first time Google does this for Android. Really nice. But of course this preview is not free of bugs. To help us all get a more stable final release, give feedback or issue bug reports, if you encounter anything that bothers you or is a bug. There is a special L preview issue tracker.

And that's it for today

I started this post as part of the preparation for my talk at the July meetup of the Dutch Android User Group.

I had much fun presenting about this topic at the July meetup of the Dutch Android User Group. And I had fun digging into this topic - and still have. Reading the source of RecyclerView and its many inner classes is really interesting. Thanks to the organizers for giving me the opportunity to speak about this topic and for forcing me to dig into this stuff

At Utrecht I had 15-20 minutes for my talk. How I managed to get it done in time is still a mystery to me. As you can see there's a lot to talk about - and this post is only the beginning.

Until next time!

The post A First Glance at Android’s RecyclerView appeared first on Grokking Android.

Mostly I think Cyril's arguments are valid.

I wouldn't object to another language besides Java. Especially since the ability to use the new features of Java 8 might still be far away on Android.

But what about Scala, Groovy or the like, you might ask. Well, I think Dart being a first class, Google supported citizen would be another matter altogether. Despite the fact that I agree mostly with Cyril's post, I think the post needs some kind of reply. And as much as I love Google plus, I think it's not the appropriate forum for my reply. So I stick to my old-fashioned blog - with it's even more old-fashioned look

I do not know whether Dart is a superb language. I only have had quick perfunctory glances on slides or the odd look at the dartlang.org website whenever the topic Dart crept up. I also missed the Google Dart flight school this winter and haven't develop anything decent in Dart at all. Yet from what I've read it looks like a decent enough and modern language that I would like to dig into. So Google bringing it to Android? That would be a very good reason for me to finally have a deeper look

What's important: Whatever Google comes up with, I strongly believe it's going to run on ART. I wouldn't be too surprised to learn that the initial reason to create a new VM in the first place, was inspired by Google's wish to support other languages better. But as everything in this post, that's just mere speculation. Pure guesswork.

There is a big reason for this: It's the easiest path to migration. It allows people to keep using existing libraries (no matter whether those are plain old Java libraries or specific Android library projects). If those libraries couldn't be used anymore, any other language would have a very difficult start.

It might also allow different teams of bigger organizations (think Facebook, Twitter, or those over-careful and very slow-movers like banks and insurances) to use both languages for one app (or app family). The hip front end team already uses Dart while those taking care of the database, synchronization and what not, keep using Java (for the time being). Cyril left this one very vague. I can't understand why? For me that's a necessity. Without it there's no successful path to a quick adoption.

If there is one thing, where I didn't agree with Cyril, it's his paragraph, where he suggests that Dart could be the one language for all of Google's projects. Such that Google could get rid of Python, Java, C++ and whatever else they use. I don't think that's feasible. For two reasons:

1. The question of existing libraries exists for Google projects as well. Of course Google could reinvent the wheel all the time - they have enough people to do so. But that would be a foolish waste of energy. I don't think it's likely that Google is going to do that.
2. One language is rarely suited for all kind of development efforts. That was never true for Java, has never been true for C and probably is not true for Dart as well. For one it's a VM language again. So whenever Google used C or C++ instead of Java or anything else, they will continue to do so instead of using Dart. And there's also the matter of the existing code base and libraries only in use within Google itself. Maybe my knowledge of Dart is too superficial to see how to do that efficiently with Dart. So that reason might not be valid at all. But my guess is, that it is.

And don't forget to star issue 19266 if you want to see Dart on Android.

One last thing: Generally speaking: I hate speculations. So me taking part at a speculative rumour mill, is a big exception. Let me know if you like this kind of post. And of course, what you think about this topic. I'm interested in what you've got to say. Am I totally off? Does this sound reasonable? Is it worth speculating at all?

The post About Cyril Mottier’s “Shaping the Future of Android With Dart” – Some Additional Thoughts appeared first on Grokking Android.

I am sorry for the generalization in the headline - of course it's only me doing stupid stuff like that

Mistake of the day

Yesterday I was happily coding the sharing action for my upcoming app. This particular ShareActionProvider of the app lets users share a picture of their progress with keeping bad habits in check. I create an image and make it available to other apps via a content:// Uri. Nothing spectacular about that.

You might know that the Email app asks your ContentProvider for the display name and the file size of the shared image. The image in question is about 20K in size. That's far from being an overly big picture. Nevertheless I got the message that the attachment was too large:

This left me wondering, what might possibly be wrong. I looked at the log messages. Check. I looked at the size of the stored image. Check. I debugged into my content provider to see that it reported the correct file size. Check. Starting to go out of ideas I even adb pulled the file and opened it in an image viewer. Check - it indeed was an image. I had another look at logcat. Check. All fine. So what the heck... My curse level had increased considerably! Never a good sign.

But wait a moment. One of those checks above was not correct. Actually two of those were not correct. And - to be honest - just assuming that the message of the Email app was correct, probably was the first mistake. It totally misled me - and even worse: I let it do that.

Finally I looked a bit more carefully. It turns out that I stopped debugging my content provider too early. And that I grepped logcat too rigorously.

My content provider crashed shortly after the line where I stopped debugging, assuming everything to be perfectly fine. This assumption proved to be very wrong, since my code ran into a ClassCastException

And I didn't see it in logcat because I renamed my package a few days ago, but didn't rename my logging tag. The tag was the final part of the old app package name. And I grepped only for this tag - which proved to be very stupid! With this clever way of grepping any hints of stacktraces were gone.

Finally: I didn't notice this problem in any tests, because I do not work test first and simply had no tests for the sharing part of my provider.

BTW: I do neither get the "File too large to attach" message on an old API level 8 device, nor on my GNex or my N5. Alas I had my Nexus 7 used for testing, which I update rarely since it's a testing device only. The Email app seems to have been fixed. So with any of my other testing devices, I probably wouldn't have had the same problems. It was just one of those days

Lessons learned

Actually running into stuff like this is not all bad. Okay, granted: It is. I wasted too much time with it. But the good part is, that it's just another lesson along the way. And a lesson I probably won't forget that soon.

For this day my takeaways were:

• Do not trust messages of other apps
• Do not rename packages without renaming logcat tags as well
• Stop being so sloppy with your tests

That's it for today. The next post in this series will have the name "Be careful with that package name, Eugene". Obviously it nicely fits the scheme of this post since it's just another package name mishap.

Have you experienced anything like that? If so, please let us know in the comments. Don't let me be the only fool around

The post Stupid mistakes devs make, part I: Taking app messages at face value appeared first on Grokking Android.

Sample project

I have created a sample project for the server side of upstream messaging with Google Cloud Messaging. Please note that this is a sample. It's not suitable for production!

Permanent connection and XMPP

Just recall the flow of events, described in detail in my first post:

For this flow to work, Google must contact your server whenever the user sends a message from his device upstream to Google's cloud. There are many models of how to do that. The one chosen by Google is to require a permanent connection between your backend and one of Google's endpoints.

That's where XMPP comes into play. Google has chosen XMPP as the protocol of choice for communicating between its servers and your server. Google named its XMPP endpoint "GCM Cloud Connection Server" or CCS for short. XMPP is an XML-based protocol that was created for instant messaging (also known under it's original name Jabber). You can read more about XMPP on Wikipedia.

Server side code

In the previous post about upstream messaging you have seen that the Android side of GCM messaging is as simple as it can get.

The server side though is another matter altogether and got more complicated with the new solution.

First of all you're most likely not as familiar with XMPP as you are with HTTP. And you're not alone with it. HTTP is probably the most used application layer protocol. Thus the online knowledge base for HTTP is huge. Less so for XMPP. You probably have to search longer for solutions when hitting a stumbling block with XMPP.

This situation also applies to libraries. While there is an abundance of HTTP libraries, there are way less for XMPP. For Java I have found only one library that is still actively maintained: The Smack library, which Google also uses in its sample code.

Luckily Google has a very detailed description of all the message types exchanged between your server and Google's cloud. And since XMPP is text-based you could build a client on your own - no matter which language you use. Nevertheless I recommend to use a library for this - after all they not only ease your life but are also more heavily tested. It's likely that others already have found a solution for a problem that would otherwise bite you in production when writing your own code.

I have taken Google's sample code for XMPP and extended it to be more flexible and suit my needs. This code requires the Smack and the json-simple libraries. To repeat: The demo is there just to get you up and running, so that you can easily test the upstream messaging model and your Android code. It's still very basic and rough!

Logging messages

When setting up the connection using Smack's XMPPConnection, you can configure it to open a Swing window displaying all incoming and outgoing messages:

config.setDebuggerEnabled(mDebuggable);

I set the flag to true when using the main() method of CcsClient. That obviously wouldn't work too well on a server so I made this configurable. From within my web project I set this flag to false.

There is another flag that configures if Smack logs every message:

XMPPConnection.DEBUG_ENABLED = true;

Within the sample code I simply set this to true to see every message. Very handy for finding problems during development and appropriate for this demo project.

Implementing a server

These are the things you have to take care of:

• Establish the connection
• Authenticate your server app
• Receive messages from Google's cloud
• Send messages to Google's cloud
• Acknowledge messages
• Deal with problems

Since all message types are described in detail on Google's Cloud Connection Server page, you can use whatever solution you like. The following code samples are in Java and make use of the Smack library. While some stuff is from Google's sample code, some contains additions and abstractions around that sample code.

The most important class is CcsClient. This class is responsible for logging in to the server, sending messages to Google's Cloud, receiving incoming messages and handling ACKs and NACKs correctly.

Connect to the GCM Cloud Connection Server

For the permanent connection you open a TLS secured connection to gcm.googleapis.com at port 5235.

Within CcsClient the method connect() handles this. It needs a ConnectionConfiguration object.

Here's how to set up the ConnectionConfiguration:

config = new ConnectionConfiguration(GCM_SERVER, GCM_PORT);
config.setSecurityMode(SecurityMode.required);
config.setReconnectionAllowed(true);
config.setRosterLoadedAtLogin(false);
config.setSendPresence(false);
config.setSocketFactory(SSLSocketFactory.getDefault());

In the first line you specify which server and which port to use. As mentioned these have to be gcm.googleapis.com and 5235 respectively. And you have to ensure to use Transport Layer Security (TLS). That's why you have to set the SSLSocketFactory.

Afterwards you can create a Connection object and use it to establish the connection to Google's servers:

Connection connection = new XMPPConnection(config);
connection.connect();

Authenticate your server app

Google needs to ensure that you are allowed to send messages via Google Cloud Messaging - and that you are allowed to send them to the clients you are addressing. For this Google uses a project id and an API key specific for that Google Cloud project.

I have detailed in my previous post about upstream messaging how to create a project and how to generate a server API key for that project.

With XMPP you do not send the API key with every request. Instead you authenticate your server app directly after establishing the connection.

In Java just use the Connection object you created in the previous step to log in:

connection.login(mProjectId + "@gcm.googleapis.com", mApiKey);

Obviously you have to use the values created on Google's Cloud Console for mProjectId and mApiKey. You either pass them as arguments to the main() method of CcsClient or you call prepareClient() with the correct values - which I do from within my web project.

After logging in, you can send and receive messages.

Message formats

Before I will cover how to send or receive messages, I'm going to show you some typical messages sent either from your server or back to your server.

Incoming upstream messages

The following is a message as it shows up on your server when a user clicks "Register" in the Android client sample:

<message 
      to="projectId@gcm.googleapis.com" 
      from="devices@gcm.googleapis.com">
   <gcm xmlns="google:mobile:data">
      {
      "category":"com.grokkingandroid.sampleapp.samples.gcm",
      "data":
         {
         "action":
            "com.grokkingandroid.sampleapp.samples.gcm.REGISTER",
         "account":"info@openminds.de"
         },
      "message_id":"20",
      "from":"someRegistrationId"
      }
   </gcm>
</message>

This message is no different from any other message sent from an Android device. It is obvious that the message consists of an outer XML part and an inner JSON part. You can safely ignore the XML part. It's always the same and is only used since XMPP is an XML based protocol. What's important is the JSON part. The JSON object contains all the attributes you need to react appropriately to incoming messages.

All upstream messages contain the following attributes:

Obviously only your apps can send data to your server. But you can use the same GCM server for multiple apps. That's why the category attribute is needed.

The data attribute is where you can put all the stuff, that you want to transmit to your server. The value of the data attribute is a JSON object itself.

The registration id is sent with every message within the from attribute. It's a very lengthy string which you must use to map the data to the correct user.

ACK messages

The next section explains what's up with the ACK and NACK messages. For now, you just need to know what those messages look like.

An ACK message is the simpler of both and always looks the same:

<message>
   <gcm xmlns="google:mobile:data">
      {
      "message_id":"m-8238983812089683316",
      "message_type":"ack",
      "from":"someRegistrationId"
      }
   </gcm>
</message>

Incoming NACK messages

NACK messages come in two types. A stanza message always indicates a malformed message on your side. Stanza is the weird name used in the XMPP specification for the different kinds of XML messages that XMPP supports. Any other erroneous condition is handled by the second type of NACK messages.

Let me show you a stanza message first:

<message 
      id="iUB3B-2" 
      to="someProjectId@gcm.googleapis.com" 
      type="error">
   <error 
         code="400" 
         type="MODIFY">
      <bad-request 
            xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
      <text 
            xml:lang="en" 
            xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
            InvalidJson: JSON_PARSING_ERROR
                  : Missing Required Field: message_id
      </text>
   </error>
   <gcm xmlns="google:mobile:data">
      {
      "to":"someRegId",
      "delay_while_idle":true,
      "data":
         {
         "message":
               "Simple sample sessage"
         },
      "time_to_live":120000
      }
   </gcm>
</message>

The error element of the XML message contains the description of what went wrong. And the gcm element contains the complete message you have sent to the server. The descriptive error message together with the full message causing the problem makes it really simple to understand what went wrong. In this case, the message_id is missing. I won't go into detail for this type. You get those messages only, if you do not provide all mandatory attributes.

Stanza error messages should only happen while developing your app. What might follow later on are other problem types. Here is a sample message for other failure situations:

<message>
   <gcm xmlns="google:mobile:data">
      {
      "message_id":"m-4370299872608467243",
      "from":"invalidRegId",
      "error":"BAD_REGISTRATION",
      "message_type":"nack"
      }
   </gcm>
</message>

In this case the registration id you sent to Google's server is invalid. Note: You will also get NACK messages for as long as your sign-up form hasn't been processed by Google.

Outgoing messages to devices

The final message type is a message from your server to an Android device:

<message id="4icfN-5">
   <gcm xmlns="google:mobile:data">
      {
      "to":"someRegistrationId",
      "delay_while_idle":true,
      "data":
         {
         "message":"Test message to a registered device"
         },
      "message_id":"m-15",
      "time_to_live":10000
      }
   </gcm>
</message>

Some of the attributes for sending messages via the Cloud Connection Server are the same as with messages via Google's HTTP server. Others though are new and still others are missing. The following table shows a list of all possible attributes for sending XMPP messages to a device.

If you have used GCM in the past you will notice the to attribute. That's the XMPP replacement for registration_ids. And in contrast to registration_ids you can send a message to only one user. Which means that for a broadcast you have to iterate over all registration ids. See Google's documentation for details.

The delay_while_idle attribute tells Google that it should not send a message when the client device is not active. A value of true means that messages are kept on Google's server until the device is active again.

The collapse_key probably needs some more explanation. If a device is offline you do not want it to get swamped with messages when it goes online again. Instead you can use the attribute collapse_key to ensure that only the last message for this key gets delivered to the app. But note: You can use only four collapse keys at the same time. The collapse_key applies to messages not delivered right away because of an delay_while_idle flag, but also to messages than cannot be delivered because the device isn't connected at all.

You might have noticed that the data attribute is optional. Now at first this might sound like a pointless exercise. Why send a message without any data in it? But it depends on the purpose of the message. You can use a GCM message as a tickle. To simply notify your app, that there's new data on the server to download. Unless the app can download different types of data, an empty message would be enough. When such a message arrives, your app would try to contact your server and download what it has to know.

If you do not set a time_to_live value, the default is used. The default currently is four weeks.

Message acknowledgements

The GCM Cloud Connection Server expects your server to acknowledge each and every method it sends to you. Google states explicitly that you should never send a NACK!

Always having to acknowledge messages means you should be able to deal with those messages. Take care of exceptional conditions, that might come up at your end. Google will resend messages for which you fail to send an acknowledgement. So not acknowledging puts unnecessary burden on your server.

Here's what Google expects your server to adhere to:

For each device message your app server receives from CCS, it needs to send an ACK message. It never needs to send a NACK message. If you don't send an ACK for a message, CCS will just resend it.

Source: https://developer.android.com/google/gcm/ccs.html

Google sends back ACK or NACK messages for every message your backend sends towards Google's cloud. Google obviously is allowed to send NACKs. A NACK coming from Google means that you did something wrong - most of the time at least. For example you will get NACK messages for trying to send messages to registration ids that aren't valid anymore.

Google will also send NACKs if the service is down or in case an "Internal Server Error" occurred. In the first case you should simply queue the message to resend it sometime later. In the second case though, you are a bit on your own. Most likely resending should be fine since most other cases are handled with other exception codes. So most likely it's a problem on Google's end - but you cannot know for sure. Maybe the problem is caused by the content of your message after all. It might be a good idea to add an internal retry counter which you decrease with every transmission. At the very least log those cases and have a look at them.

Receive messages from Google's cloud

To handle incoming messages with Smack, you first have to register a PacketListener object with the Connection you created in the first step above. This object is responsible for all incoming traffic. See this slightly adapted version of Google's code:

connection.addPacketListener(new PacketListener() {
   @Override
   public void processPacket(Packet packet) {
      Message incomingMessage = (Message) packet;
      GcmPacketExtension gcmPacket =
            (GcmPacketExtension)incomingMessage
                  .getExtension(GCM_NAMESPACE);
      String json = gcmPacket.getJson();
      try {
         Map jsonMap =
               (Map)JSONValue.parseWithException(json);
         
         handleMessage(jsonMap);
      } catch (ParseException e) {
         logger.log(Level.SEVERE, "Error parsing JSON " + json, e);
      } catch (Exception e) {
         logger.log(Level.SEVERE, "Couldn't send echo.", e);
      }
   }
}, new PacketTypeFilter(Message.class));

And handleMessage() looks like this:

private void handleMessage(Map<String, Object> jsonMap) {
   // only present for "ack"/"nack" messages
   Object messageType = jsonMap.get("message_type");
   if (messageType == null) {
      // Normal upstream data message
      CcsMessage msg = getMessage(jsonMap);
      handleIncomingDataMessage(msg);
      // Send ACK to CCS
      String ack = createJsonAck(msg.getFrom(), msg.getMessageId());
      send(ack);
   } else if ("ack".equals(messageType.toString())) {
      // Process Ack
      handleAckReceipt(jsonMap);
   } else if ("nack".equals(messageType.toString())) {
      // Process Nack
      handleNackReceipt(jsonMap);
   } else {
      logger.log(Level.WARNING, "Unrecognized message type (%s)",
      messageType.toString());
   }
}

The PacketListener has just one method: processPackage() which takes a Packet as argument.

A data package - that is an upstream message coming from a device - is then delegated to handleIncomingDataMessage(). For my sample project I have modified Google's original code quite a bit. For one I use a CcsMessage object here that represents the incoming message.

Next I use PayloadProcessors to deal with the different type of messages. For every possible type of message I have a specific implementation of this interface to actually deal with the incoming message. You can of course replace this logic with whatever suits you.

What you do within those PayloadProcessors is very app-specific. The sample code just provides very basic implementations to give you an understanding of how to deal with messages. Hopefully your app has more to offer than my sample

Send messages to Google's cloud

To send a message to Google's Cloud Connection Server, you have to follow these steps:

1. Create the JSON payload
2. Create a Smack Packet for the message
3. Send the XML message to Google's cloud

Create the JSON payload

With json-simple you can create a JSON object from is a map by calling JSONValue.toJSONString(). Each key of the map corresponds to one JSON attribute. In the section about message types I have listed the possible attributes. With this you can first create the map:

public static Map createAttributeMap(
      String to, 
      String messageId, 
      Map<String, String> payload,
      String collapseKey, 
      Long timeToLive, 
      Boolean delayWhileIdle) {
   Map<String, Object> message =
         new HashMap<String, Object>();
   if (to != null) {
      message.put("to", to);
   }
   if (collapseKey != null) {
      message.put("collapse_key", collapseKey);
   }
   if (timeToLive != null) {
      message.put("time_to_live", timeToLive);
   }
   if (delayWhileIdle != null && delayWhileIdle) {
      message.put("delay_while_idle", true);
   }
   if (messageId != null) {
      message.put("message_id", messageId);
   }
   message.put("data", payload);
   return message;
}

Using this method creating a JSON string for sending a message is simple:

public static String createJsonMessage(
      String to, 
      String messageId, 
      Map<String, String> payload,
      String collapseKey, 
      Long timeToLive, 
      Boolean delayWhileIdle) {
   return createJsonMessage(
         createAttributeMap(
               to, 
               messageId, 
               payload,
               collapseKey, 
               timeToLive, 
               delayWhileIdle));
}

public static String createJsonMessage(Map map) {
   return JSONValue.toJSONString(map);
}

Create a Smack Packet for the message

Creating a Packet object is even simpler. Google's code makes use of the extension mechanism of Smack. Smack's extensions are handlers for specific message types. The code uses them for processing incoming as well as outgoing messages.

Google's inner class GcmPacketExtension is an implementation of Smack's PacketExtension interface.

It's method toPacket() creates an XML Packet, in this case it wraps the JSON with appropriate XML as required by XMPP.

Packet request = new GcmPacketExtension(jsonRequest).toPacket();

Send the message to Google's cloud

If you have a Packet object you simply call send() on your XMPPConnection object that you created connecting to Google's server in step one.

My demo follows Google's sample code in combining the last two steps in the method send() of the CcsClient class:

public void send(String jsonRequest) {
   Packet request = new GcmPacketExtension(jsonRequest).toPacket();
   connection.sendPacket(request);
}

Sending to multiple recipients via Google's Cloud Connection Server

You cannot send a message to multiple recipients when using Google's Cloud Connection Server. Instead you have to send one message for every registration id you want to send a message to. That's why I added the message sendBroadcast() which simply iterates over all recipients:

public void sendBroadcast(Map<String, String> payload, String collapseKey,
      long timeToLive, Boolean delayWhileIdle, List<String> recipients) {
   Map map = 
         createAttributeMap(null, null, payload, 
         collapseKey, timeToLive, delayWhileIdle);
   for (String toRegId: recipients) {
      String messageId = getRandomMessageId();
      map.put("message_id", messageId);
      map.put("to", toRegId);
      String jsonRequest = createJsonMessage(map);
      send(jsonRequest);
   }
}

Note: There actually is one option to target multitple registrations ids with just one message. With user specific messages you can target all devices of one user. But you're still limited to one user only with this option. Since I'm going to cover user specific messages in my next post, I won't deal with this option here.

You can combine HTTP and XMPP

Google allows you to use HTTP at the same time as XMPP to send messages to devices. It's up to you if you want to use XMPP just to receive upstream messages of devices and to acknowledge those messages or if you want to use XMPP to talk to Google's Cloud Connection Server (CCS) for everything.

Actually there is one use case for which you have to use HTTP - at least at the moment. I very much hope that this will change when the final version of those new services is released for everyone. I will cover that specific use case next week.

One final thing

I have written most of the server code in preparation of my talk at the Dutch Android User Group meetup. As I have written in my previous post about Google Cloud Messaging, you have to sign up to use the new features like upstream messaging, XMPP or user notifications. After signing up, Google processes your request and some time later comes back with the approval. In my case the approval took a while and the preparation for the talk was in jeopardy.

Gladly Dennis Geurts offered to use his testing API key and project id for which he had signed up much earlier. A big thanks for that, Dennis!

Lessons learned

With this post I have shown you some aspects of the server side of Google Cloud Messaging using the new upstream messaging model.

You have seen the different message types, have heard of the need to acknowledge messages and how to receive and send messages using Smack's Java library for XMPP. Since XMPP is text based those code snippets should be easy to transform to any other language.

Together with the source of the demo project this post should get you on the right track to set up your own project.

If you want to start using Google Cloud Messaging, be sure to read the official documentation. I couldn't cover all in this post. Be sure to not forget the document about advanced topics. There is also a nice blog post by Ryan Oldenburg of Pushbullet about some thinks to keep in mind when using GCM. It might help you to avoid problems right away. For another perspective on the topic you might also want to read Antoine Campbell's Cloud Connection Server Tutorial.

One final problem: Right now I don't know any SaaS or BaaS provider to support the XMPP messaging model for Google Cloud Messaging. This is a serious limitation in my opinion - one which I expect to get much better when this model gets adopted more often and is published to all without approval process. Should you know of any provider supporting the new GCM model, please drop me a line.

The post An XMPP Server for Google Cloud Messaging appeared first on Grokking Android.

I had never written these posts if it weren't for the Dutch Android User Group meetup in Utrecht (January 2014), where I had the pleasure to talk about this topic. This event was well-attended and was packed with interesting talks about the changes in Android 4.4 and Google Play Services. If you have ever the chance to attend a meetup of our Dutch colleagues, I strongly suggest to do so. It has been a gorgeous evening and was well worth the two-hour drive. It was not just the talks but also the overall atmosphere as well as the conversations during the breaks and afterwards. A big thanks to the organizers for the awesome evening!

You can find my slides on the speakerdeck site. And a video of the talk should also be available pretty soon.

Sample App

I have published sample apps on github where you can see how to use this in context. For the Android client clone the gcm_sample project. For the server clone the gcm_server project.

What's new

With Google Play Services 3.1 Google made some changes to Google Cloud Messaging:

• You can send messages upstream from the user's device
• You have to use a permanent connection between your backend and Google's services
• You can use user specific notifications

In this post I will only cover upstream messaging. That is the flow of events and what to do on Android's side. In my next post I'm going to cover the server side - and in the third post I will write about user specific notifications. User notifications allow you to send user specific messages with the possibility to cancel notifications on other devices if they have been consumed already on one device.

Upstream messaging

With the new GCM release Google allows you to send messages directly back to Google's cloud. That's what they call upstream messaging. Have a look at the following diagrams. The first one is the traditional model of Google Cloud Messaging while the second one shows the new flow of events.

The first two steps in both diagrams are the same: You tell the Google Cloud Messaging API that you want to register a device (step 1). If the registration succeeds Google returns the registration id for this device (step 2).

Traditionally you would then send the registration id back to your server (step 3). The protocol was up to you but very likely HTTP. The server would (hopefully) respond with a success message (step 4).

From then on your server could send messages to Google's Cloud Messaging service (step 5) and the user's device would receive it, if it's registration id was part of the registration_ids parameter of the message (step 6).

With upstream messaging though your app would send the registration id (step 3) not directly to your server, but instead call a method of the Google Play Services API. Google Play Services would then send the message to Google's servers.

Google then processes the message and sends it to your backend. Obviously for this to work your backend must be connected in some way to Google's cloud. I will deal with this part in my next post. For now it's enough to know that there has to be a permanent connection between your backend and Google's cloud and that Google will deliver messages that way (step 4).

After the registration id has been transmitted successfully you can send messages to the device (step 5). But with the new way to use Google Cloud Messaging you would use the existing connection between your server and Google's servers and use a different protocol (with slightly different parameters).

Note that Google uses different names for its servers depending on which transmission model you want to use. Google uses the name "GCM HTTP Connection Server" for those servers receiving HTTP messages and it uses "GCM Cloud Connection Server" for those receiving XMPP messages via the permanent connection. The abbreviation CCS is very commonly used within GCM's documentation.

Create your credentials

If you already use Google Cloud Messaging you can skip this part and proceed to the next section.

If you're new to Google Cloud Messaging, you have to create an API key in Google's Cloud Console/Google Developer Console. Do not confuse it with the Google Play Developer Console. Both are unrelated.

After logging in to the Cloud Console you will see a list of projects. Simply create a new one and give it a name and a project id in the next dialog. Now this could be a source of confusion. The project id you use here is not the project id you have to use in your code later on. It's just a name which nevertheless has to be unique.

Afterwards creating the project the developer console will show you the project's page. Go to "APIs & Auth" in the menu and turn on "Google Cloud Messaging for Android" in the huge list of Google's services. Since Google displays all your active services at the top, the entry will move directly to the top after you enable it. Don't be irritated by that tiny UX glitch. Simply scroll to the top and you will see that it's status has changed to "On". That's great.

Switch to Credentials in the menu on the left. At the top of the new screen you can find a client id. It starts with a number followed by ".apps.googleusercontent.com". Select the number (only the number), copy it and paste it into your strings.xml - or a special gcm_strings.xml that only contains the project id. Name the string whatever you like - in the sample project I expect a string named gcm_project_id.

That's all you need for the Android part. But since you're logged in to the dev console anyway, let me show you how to create the API key for your server right away.

Go back to the dev console. On the Credentials page there are two sections. The OAuth section on the top is where you have found the project id. Below of it is the section called "Public API access". It's still empty. Click "Create New Key" and in the next dialog select "Server key". Afterwards you will see the API key for server applications together with some additional information. You will use the API key when following my post about the server side of GCM.

Sign up for using the new features

To be able to use all the shiny new features of Google Cloud Messaging, you have to sign up first. With the sign up form you "Sign up to be a trial partner". The new services are not yet finalized. It's a bit like it has been with Google Cloud to Device Messaging (C2DM) - the predecessor to GCM. You had to sign up as well, and when the service was finally made public, it had evolved to Google Cloud Messaging. So expect the API to change!

Using Google Play Services

You need to use Google Play Services from within your app for registering the device for as well as for sending upstream messages.

Setting up Google Play Services is easy, but requires too many steps to cover them in this post. And those steps also are different depending on whether you use Android Studio, Eclipse or something else. Have a look at the Play services documentation if it's the first time you use Google Play Services.

The very first step in your code when using Google Play Services is to make sure that Google Play Services are available at all. You can do so with the following snippet:

private boolean checkPlayServices() {
   int resultCode = 
         GooglePlayServicesUtil
            .isGooglePlayServicesAvailable(getActivity());
   if (resultCode != ConnectionResult.SUCCESS) {
      if (GooglePlayServicesUtil.
            isUserRecoverableError(resultCode)) {
         GooglePlayServicesUtil.getErrorDialog(
               resultCode, 
               getActivity(),
               RC_RES_REQUEST).show();
      } else {
         Log.i("grokkingandroid", 
               "This device is not supported.");
      }
      return false;
   }
   return true;
}

What to do when the services are not available, depends on how important they are for your app. If Play Services are not essential, I suggest to let the user know - but in an unobtrusive way. After all the app is usable without it, so do not annoy your users with dialogs or other stuff that keeps them from doing what they actually installed the app for.

Registering the device for Google Cloud Messaging

The next step is to register the device. Google needs to know about your device before your app is allowed to receive or send messages.

In my sample app the user has to explicitly click the button register. Not a typical use case, but for the sample this makes sense. Now when to do this is in a real app is up to you. But when your app benefits from Google Cloud Messaging you usually want to register the device as soon as possible.

I also let the user select a Google account. Your app's users do not need one for Google Cloud Messaging. I solely request one to use this account for user specific notifications. I will cover those in the third post of this series.

Registering actually is very easy. First get hold of a GoogleCloudMessaging object and then simply call its method register() passing in the project id of the dev console (see "Create your credentials" above):

String projectId = 
      getResources().getString(R.string.gcm_project_id);
GoogleCloudMessaging gcm = 
      GoogleCloudMessaging.getInstance(this);
String regid = gcm.register(projectId);

Be careful though: Asking for the registration id is a blocking request. Hence, you should always use the call in a separate thread off the main thread (UI thread). In the sample project I am using an IntentService to achieve this.

Send messages upstream

As soon as the device is registered, it can send messages upstream - as well as receive messages. Probably the very first message to send upstream is the newly received registration id.

Sending messages is nearly as simple as registering. You create a Bundle with all the payload data you want to transmit and you also have to create a unique message id. In my sample code I simply increase a counter I keep within the SharedPreferences for the message id. Depending on your payload the code might look more or less like this:

try {
   Bundle data = new Bundle();
   // the account is used for keeping 
   // track of user notifications
   data.putString("account", account);
   // the action is used to distinguish 
   // different message types on the server
   data.putString("action", Constants.ACTION_REGISTER);
   String msgId = Integer.toString(getNextMsgId());
   gcm.send(projectId + "@gcm.googleapis.com", msgId,
         Constants.GCM_DEFAULT_TTL, data);
} catch (IOException e) {
   Log.e("grokkingandroid",
         "IOException while sending registration id", e);
}

As you can see you once again need a GoogleClientMessaging object and call its send() message.

This message takes as parameters the project id appended with the fixed string "@gcm.googleapis.com", a unique message id, a time to live value and the bundle with your payload.

You might notice that I do not include the registration id as part of the payload. That's because Google Play Services adds the registration id to every message to your backend anyway. You will see in the next post which parameter Google uses for the registration id. For now, just keep in mind that above code is all that is actually needed.

Those strings within the bundle are not even necessary. I use the account because I want to send user specific messages and I use the action to differentiate on my server between different message types.

As you can see there is no special message for sending the registration id back home. It's just a message like any other upstream message.

Benefits of Upstream messaging

Now that you know how to send upstream messages, you might wonder about why to use upstream messaging in the first place. Why not send your message back to your server as you always did (assuming you did contact your server)?

There are three reasons on the Android side for using the new model:

• The upstream messaging API is dead simple
• Upstream messages can reuse connections
• Upstream messages are needed for notification cancellation

The API is dead simple

You have seen how simple the Android code is. It's just some message calls to Google Play Services's GoogleCloudMessaging class. It's really just this one class, which with only six public methods is not too difficult to grasp

Contrast that with using HTTP instead: When talking back to your own servers directly you have to take care of checking if the network is available, send off the message, check for any error conditions and enqueue the message for later delivery if anything goes awry. All in all you're better of with upstream messaging - at least for as long as you only care about the Android code.

Upstream messages can reuse connections

Not only is the API easier to use, it can also save resources. The user's device has a connection to Google anyway so with upstream messaging Google Play Services can reuse this connection. The services take care of using the most power efficient way to send messages so you do not have to deal with that. This helps keeping the battery usage of your app to a minimum.

Of course if your app only sends messages every once in a while, your users won't notice any change in the battery usage. But if your app has to send many messages to your backend, this might make a difference to your users.

Upstream messages are needed for notification cancellation

The strongest argument for using upstream messaging though is notification cancellation. If you send messages from your server to specific users, you do not want them to see a notification on each and every device - even if it has long been read on another device. I will deal with user specific messages and notification cancellation in my third post about Google Cloud Messaging. So stay tuned

Permissions

To use Google Cloud Messaging you need quite a lot of permissions:

<uses-permission 
   android:name="android.permission.INTERNET" />
<uses-permission 
   android:name="android.permission.GET_ACCOUNTS" />
<uses-permission 
   android:name="android.permission.WAKE_LOCK" />
<uses-permission 
   android:name="com.google.android.c2dm.permission.RECEIVE" />
<permission 
   android:name=
      "com.grokkingandroid.sampleapp.samples.notifications.gcm.permission.C2D_MESSAGE"
   android:protectionLevel="signature" />
<uses-permission 
   android:name=
      "com.grokkingandroid.sampleapp.samples.notifications.gcm.permission.C2D_MESSAGE" />

The first three are predefined permissions. You might notice the account permission. Actually this one is only needed for API levels before Android 4.0.4. I added it for completeness.

The fourth is a bit of an oddity. It's the old Cloud to Device Messaging (C2DM) permission. For backwards compatibility it makes sense to not change it - otherwise existing apps had to ask for a new permission. But it looks weird about two years after C2DM was deprecated.

You also have to create a new permission of your own. That's the permission that ensures that no other app can receive messages intended for your app. It has to exactly follow this naming convention: Package name plus ".permission.C2D_MESSAGE". Otherwise your app won't receive the messages sent to it. Your app also must use this newly created permission.

Receiving messages

Of course the fun part of Google Cloud Messaging is to actually receive push messages from the cloud. Google transmits the messages to your app to a BroadcastReceiver.

The following code is basically the same as Google's sample code on their client page:

/**
 * See http://developer.android.com/google/gcm/client.html
 */
public class GcmBroadcastReceiver 
      extends WakefulBroadcastReceiver {
   @Override
   public void onReceive(Context context, Intent intent) {
      // Explicitly specify that
      // GcmIntentService will handle the intent.
      ComponentName comp = 
            new ComponentName(
               context.getPackageName(),
               GcmIntentService.class.getName());
      // Start the service, keeping the 
      // device awake while it is launching.
      startWakefulService(
            context, 
            (intent.setComponent(comp)));
      setResultCode(Activity.RESULT_OK);
   }
}

The Broadcastreceiver gets the message - but since it runs on the UI thread it should immediately pass the message on to some background thread. I use the same IntentService you have already seen for registering the device.

Actually parsing the message and doing what has to be done is done in the service. Again The code is pretty much the same as on Google's documentation:

// handling of stuff as described on
// http://developer.android.com/google/gcm/client.html
try {
   Bundle extras = intent.getExtras();
   // The getMessageType() intent parameter
   // must be the intent you
   // received in your BroadcastReceiver.
   String messageType = gcm.getMessageType(intent);
   
   if (extras != null && !extras.isEmpty()) {
      /*
      * Filter messages based on message type. 
      * Since it is likely that GCM will be 
      * extended in the future with new 
      * message types, just ignore any message 
      * types you're not interested in, or that you
      * don't recognize.
      */
      if (GoogleCloudMessaging.MESSAGE_TYPE_SEND_ERROR
            .equals(messageType)) {
         sendNotification(
            "Send error: " + extras.toString());
      } 
      else if (GoogleCloudMessaging.MESSAGE_TYPE_DELETED
            .equals(messageType)) {
         sendNotification("Deleted messages on server: "
            + extras.toString());
      } else if (GoogleCloudMessaging.MESSAGE_TYPE_MESSAGE
            .equals(messageType)) {
         // Post notification of received message.
         String msg = extras.getString("message");
         if (TextUtils.isEmpty(msg)) {
            msg = "empty message";
         }
         sendNotification(msg);
      }
   }
} finally {
   // Release the wake lock provided by the WakefulBroadcastReceiver.
   GcmBroadcastReceiver.completeWakefulIntent(intent);
}

As you can see GCM uses different message types. the last one is the one actually containing a new messages. The first one informs you about errors when sending messages and the second tells you that messages have been deleted. If for example you display incoming messages with a notification you would have to cancel the notification in this case.

What to do when receiving an actual message is very specific to your app. The sample app simply displays a notification.

Do not forget to release the wake lock. That's the line within the finally block. The finally block ensure that this call will always be done - even if any exception has been thrown in the code within the try block. Be sure to do it that way!

Lessons learned

In this post you have seen how the message flow has changed when using Google Cloud Messaging. With the previous model you had to contact your server directly from the device, now you only tell Google Play Services what to do with the new upstream messaging model. Google's services take care of actually delivering the message to your server.

You also have learned about how to set up the project in Google's developer console and that you have to sign in to use the new features.

Finally you have seen how easy the Android code actually is and what the benefits of upstream messages are.

In the next post you will learn more about the server side of upstream messaging - which is a tad more complex. And after that I'm going to show you how to use user notifications in the final post of this series.

The post Upstream Messages With Google Cloud Messaging appeared first on Grokking Android.

To make this work, Chrome apps have to use a thin wrapper to be considered a "native" app and to access phone functions not available via HTML 5 as of yet. For this Google uses Apache Cordova, better known as Phonegap. With the help of this project and further additions made by Google, Chrome apps can be published on Google Play and Apple's App Store. You can read more about it on Google's blog post.

Users cannot recognize those apps as Chrome apps in the respective app stores. They just show up as any other app. And that's where the problem starts.

Taking a web app, which works fine on a desktop, wrapping it with some tools and publishing it, that's just not enough. Those apps would fall short of users' expectations.

First of all those apps would look totally out of place. Just have a look at this screenshot of Google's blog post:

There's no action bar, those buttons look weird, the header is very unusual - it just doesn't fit. Of course you could get around most problems and make it look properly - but that would require some additional work. You would no longer just wrap an existing app, but start to provide platform specific deviations to achieve proper designs.

Secondly interaction patterns on the web, on desktop apps and on mobile apps are totally different. Consider the differences between iOS and Android alone. Tons of difference like navigation patterns, action placements, list treatment and so on. This problem is much worse and has much more influence on whether an app feels like a properly done app or not. And no cross-platform tool can help you with that. You will end up with multiple versions for all supported platforms anyway. Just consider the code. You probably can structure this in a way that is maintainable - but not if the main reason for taking this route was saving costs in the first place.

Third I wonder about the quality of the apps. This is a very personal fear based on my experience with Firefox OS apps. Those are very often normal desktop apps as well - which too often do not work on a mobile device. It might happen, that desktop app developers simply wrap up their app and do neither test properly nor know about those limitations. Of course those apps would get ratings that bad, that they wouldn't show up for most searches anyway. But Google is setting expectations for devs here - and those devs might be very disappointed down the road.

As you've seen there are plenty of issues with the user experience. But obviously technical issues exist as well.

It seems that it's not that easy from a technical point of view as Google makes us believe it is. Just have a look at the sample apps. Five (!) of those 17 apps do not run on Android at all. Another six only with limitations. Or put it another way: Only one third of those apps works properly on Android. For iOS it's about the same (though with different apps): Six apps don't work at all, another five only with limitations. Only two out of 17 apps work properly on both supported platforms! And this is about to help devs? This should be a proper way to develop cross-platform apps? Not at all!

The only thing that I am confident to work properly is the responsiveness of those apps. Web developers do that for years. They understand and grok responsiveness.

If you want to publish apps and want your users to like your apps, you have to take the patterns and specifics of each platform into consideration. That means work. No matter which approach you choose. I guess that the total amount of work is even less if you design and develop different apps for Android, iOS, Windows Phone and (hopefully) Firefox OS than when you try to use a cross-platform tool. And I have yet to see a cross-platform app that actually does work properly on different platforms.

Google has done so much in recent years to consolidate the design, interaction patterns and overall usability of Android. Which makes the recent announcement all the more disappointing. It's a step backwards. It's going back to where we were some years ago: A world without a unified design language without common interaction patterns. I do not want this. And I strongly believe, users do not want this as well.

As a developer you have to keep an eye on this project. At least because your clients might mention it. But it's not working. At least not yet. If it ever will - I do not know.

Project managers and product managers should also carefully consider the limitations of this approach. Don't think it will save you money! Don't think it will save you time! If you're not careful and use it without proper analysis, you're bound to see costs rising unexpectantly (well, actually that's to be expected) and your users will still rate your app poorly.

Note: This post has initially been written for the German publication computerwoche.de.

The post Chrome-Apps on mobile devices – a good idea? appeared first on Grokking Android.

The phone itself

I was quite suprised by the size of the device. It's roughly the same as the N5 - though the screen is much smaller and the screen resolution even more so. That's not so good - but it's a dev phone, so it's not really that important. But for any handset maker out there: If your screen doesn't provide the resolutions current top devices spout, please make your device smaller.

Of course the phone is plastic all around - it's after all a cheap phone. I do not mind. I never thought, that plastic feels cheap. Actually I prefer plastic over metal or - even worse - glass. So it feels quite good - albeit a tiny bit too large. Some rubberized finish would be a nice addition, though.

The screen is surprisingly good. Of course the resolution is far away from those of top device, but mostly good enough. Only for screens with much text, the resolution is an issue.

The camera of course isn't great - but for simple snapshots it should be sufficient. You won't ever win a price with those pictures though.

Battery life: Seems to be good, very good indeed. But that's just an initial impression. I have yet to make the phone my primary device for a few days. Something I am not quite ready to do so, yet. You will see in the next section, why not.

UX issues

FirefoxOS is full of UX issues. I'm a developer and definitely no UX expert. But even I can spot many problems. Users will notice, will stumble upon those issues and think that something's not right. So in my opinion, Mozilla should concentrate on those issues - especially some stuff that from an outside perspective looks like something that should be easy to fix. Of course I know that this outside perspective is often misleading, but hopefully some issues are easy to fix.

Touch feedback is rare. Which is a deadly sin for a touch based interface. Take the Action Bar (in FirefoxOS slang it's the Header). When I hit back in the top left corner, I want to see the back indicator highlighted. But that's not happening. So did I touch it? Should I touch again? And it's not just in the FirefoxOS Header.

Missing touch feedback is sometimes made worse by a lacking loading indicator. I want to see a spinning wheel or some other indicator that content is loading - let me know that you do something. I hit back twice over and over because I had no feedback whatsoever.

Firefox Marketplace app lacks touch feedback as well as loading indicators all over the place. And the app doesn't seem to cache anything. It feels like the app reloads all lists whenever I go back to them. That slows things down considerably and make missing feedback even worse.

The next issue might partially be based on my Android experience. But whatever the reason: I miss the back button dearly. I'm not using "up" often on android and having to go up to the Header/Action Bar feels very weird. But it's not only uncomfortable, it's sometimes even problematic. What to do on with an information dialog? I happened to stumble upon that at least once. Granted, it's the fault of the app, but nevertheless a problem that could be hurting the OS adption.

The lock screen is also a UX fail. You first have to pull up a bar from the bottom - which is nicely indicated by an appropriate animation. But afterwards you have to do another step: You have to click on the unlock icon. Two steps to unlock the phone? That's one step too much. As simple as that!

The list of opened apps also has a problem. There's a button to close this app - which works more or less randomly. Swiping the app away, though, works fine all the time.

I had some trouble with flinging through lists. One problem: When flinging repeatedly in long lists, the flow stops. Don't know how to describe this correctly. But the new movement of my finger stops the last one and starts a new fling. That feels very unnatural. It doesn't feel like a continuing movement.

Another one is the notifications drawer. You have to drag it all the way down to see the top most notification. Which is bad if you just want to peek at the notification. It feels totally strange to have to scroll that far to finally see the one notification that caused you to use the notification drawer in the first place.

The on screen keyboard also feels kind of weird to me. Cannot exactly nail it, but it just doesn't feel right. Of course on Android I swipe most of the time, but it's not just that. The spacing between keys is very narrow, but I guess that isn't it either. Hopefully I can tell you in a follow-up post, what it is that actually bothers me. Right now it's just the feeling: This is not right. The only thinkg, I can tell you for sure, is the surprising location of the "'". It's right next to the letter "l" and directly above the return key. I accidentally hit it way too often.

Apps

The general quality of the app is not great - to say the least.

One example: Pulse as one of the top apps promoted in the news category. When starting Pulse for the first time, the first thing you see, is the suggestion to get the app! WTF! I do not know about the reason, but my guess is, that this Pulse "app" is simply the mobile website. Don't know if this is Pulse's fault or Mozilla's fault, but it sheds a bad light on the platform. This shouldn't happen. This mustn't happen!

Next I downloaded a Pomodoro timer and a kitchen timer. Neither of these works when the OS goes into sleep mode. What? A timer not ringing, when the screen turns off? These seem to be apps for a desktop firefox. If they do not work properly on FirefoxOS, those apps shouldn't be available in the marketplace on these devices. Some quality assurance must take care of that. I actually found not one timer app that deals with this correctly.

Another example is the stock Camera app. When taking a photo and viewing it from within the Camera app, I sometimes got a black screen when enlarging the picture. Initially I thought the app just crashed (or run into some endless loop), but all buttons were still visible and reacted properly. Actuall it's just that the screen remains black until the enlarged picture is ready to be displayed. Which can last an astonishingly long time. This is a horrible user experience - just show me some blown up but undetailed preview of the area and display more details progressively.

The Marketplace app itself has problems. I do not want to see many apps, I want to see quality apps. One timer would be enough if it works properly and has at least a decent usability. But about ten timers and none working as expected, that's about as useful as no timer at all. I also do not need all soccer leagues of the world. I want to find the one local to me (granted, some leagues might be more interesting to others worldwide than others, but I gues most people want to see the league of their home country). Same goes for news and anything else. I am still asztonished that Google doesn't provie a better search experience on Google Play, but now I can appreciate what they have been doing. Definitely the results are more relevant than thos in Firefox market place.

Importing stuff

As an Android user I obviously have stuff on Google's server. My contacts, my calendar, mail, what not. I was able to import contacts flawlessly, but strangely enough I couldn't import any calendar information. No error dialog, it simply stopped after I entered all credentials. This is crucial and could be a big issue for FirefoxOS.

And since we're at it: A central account setting makes life so much easier. That's something Android does very well. Not just for Google accounts, mind you. But for any apps that make use of sync adapters and authenticators. It's cumbersome to have to enter the credentials over and over again because there isn't such a central place in FirefoxOS.

Initial verdict

Boy, Mozilla has still a lot to do. I still very much hope for FirefoxOS to succeed. That's why I ordered the phone in the first place. I love Android but Android needs another viable open competitor. Microsoft and Apple obviously do not fit that description.

But to be competitive in the market place, there is still much to do for Mozilla and app devs developing for FirefoxOS.

Then Mozilla needs to adress the usability issues. There are probably many more I didn't even notice. But that's what makes users recommend a system if done right. If done wrong, though, users most probably will advise against buying it. Shouldn't happen.

And of course we do need more apps. For this FirefoxOS has to gain more traction. The usual catch-22 situation of all the follow-up systems in the mobile space. That's something we all can contribute to. If you want FirefoxOS to succeeed, help Mozilla out wth an app or two

Of course all is open source, so if you want to do so you can also help with all the other issues, I mentioned. Mozilla probably would be very happy about any new contributors to the platform.

This all sounds pretty dim. But you have to consider that it's only an initial impression. Then version 1.2 is in the making and might (hopefully) correct many of the issues. I personally still have hope for the platform. So much actually that I'm giving development for it a try and to publish an app myself. I will let you know about this in a future post. But: This is still an Android centric blog. FirefoxOS related posts will only be sparse in between.

Let me know what you think and what your experience with FirefoxOS has been.

The post FirefoxOS – my Initial Impression appeared first on Grokking Android.