--- /dev/null
+[[ii-injection-and-scopes]]
+II - Injection and scopes
+-------------------------
+
+In this tutorial we'll take a closer look at the @CDIUI annotation and
+use CDI to inject some beans to our application.
+
+[[cdiui]]
+@CDIUI
+~~~~~~
+
+The @CDIUI annotation is the way in which you let the Vaadin CDI plugin
+know which UI's should be accessible to the user and how they should be
+mapped. It accepts one optional String parameter indicating the UI path.
+If an explicit path is not provided the class name of the UI will be
+used to construct a pathname by the following convention: any trailing
+"UI" will be truncated and camelcase will be converted to hyphenated
+lowercase. Some examples of the convention:
+
+....
+HelloWorldUI → hello-world
+ExampleUI → example
+VisualEditor → visual-editor
+....
+
+Passing an empty String as the path will cause the UI to be mapped to
+the root of the deployment. Most single UI applications will probably
+want to do this.
+
+[[injecting-beans]]
+Injecting beans
+~~~~~~~~~~~~~~~
+
+Now that the UI itself has been injected, we can use the @Inject
+annotation to further inject beans to it. Let's create something for us
+to actually inject.
+
+We'll define the following interface, and an implementation for it.
+
+[source,java]
+....
+package com.vaadin.cdi.tutorial;
+
+public interface Greeting {
+ public String getText();
+}
+....
+
+[source,java]
+....
+package com.vaadin.cdi.tutorial;
+
+import java.io.Serializable;
+
+public class SimpleGreetingImpl implements Greeting, Serializable {
+
+ @Override
+ public String getText() {
+ return "Hello, World!";
+ }
+}
+....
+
+So far so good, now we'll inject it into our UI. You'll need to add the
+CDI API as a dependency in your pom.xml. (Group id: javax.enterprise,
+artefact id: cdi-api, version: 1.2)
+
+[source,java]
+....
+package com.vaadin.cdi.tutorial;
+
+import javax.inject.Inject;
+
+import com.vaadin.annotations.Theme;
+import com.vaadin.cdi.CDIUI;
+import com.vaadin.server.VaadinRequest;
+import com.vaadin.ui.Button;
+import com.vaadin.ui.Button.ClickEvent;
+import com.vaadin.ui.Label;
+import com.vaadin.ui.UI;
+import com.vaadin.ui.VerticalLayout;
+
+@SuppressWarnings("serial")
+@CDIUI("")
+@Theme("valo")
+public class HelloWorldUI extends UI {
+
+ @Inject
+ private Greeting greeting;
+
+ @Override
+ protected void init(VaadinRequest request) {
+ final VerticalLayout layout = new VerticalLayout();
+ layout.setMargin(true);
+ setContent(layout);
+
+ Button button = new Button("Click Me");
+ button.addClickListener(new Button.ClickListener() {
+ public void buttonClick(ClickEvent event) {
+ layout.addComponent(new Label(greeting.getText()));
+ }
+ });
+ layout.addComponent(button);
+ }
+}
+....
+
+Let's run that and see.
+
+image:img/hello-world.png[Injection seems to be working]
+
+So far so good. Suppose we want to say hello to the user by name. We'll
+create a class to store our user data in. For now it's a simple POJO
+just for storing the name in a single string.
+
+[source,java]
+....
+package com.vaadin.cdi.tutorial;
+
+import java.io.Serializable;
+
+public class UserInfo implements Serializable {
+ private String name;
+
+ public UserInfo() {
+ this.name = "stranger";
+ }
+
+ public UserInfo(String name) {
+ this.name = name;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+}
+....
+
+We'll inject that to the UI and assign the user some name during
+initalization (for now)
+
+[source,java]
+....
+@Inject
+private UserInfo user;
+
+@Override
+protected void init(VaadinRequest request) {
+ ...
+ user.setName("Ernest");
+}
+....
+
+Then we'll create a new implementation of the Greeting and inject the
+user there as well.
+
+[source,java]
+....
+package com.vaadin.cdi.tutorial;
+
+import javax.inject.Inject;
+
+public class UserGreetingImpl implements Greeting {
+
+ @Inject
+ private UserInfo user;
+
+ @Override
+ public String getText() {
+ return "Hello, " + user.getName() + "!";
+ }
+}
+....
+
+Now, it would be easy to think that that's all you need but we're not
+quite there. There are two issues with this that need to be addressed.
+The first one will become immediately obvious when you try to deploy the
+application. The deployment will fail as the injection in HelloWorldUI
+is ambiguous, that is CDI doesn't know which implementation of Greeting
+we want. +
+There are three annotations that are useful in situations like this:
+@Default, @Alternative and @Specializes. Giving a bean any of these
+annotations will affect it's preference order when the CDI container is
+looking for which implementation to inject. Unless otherwise specified,
+beans will be considered to have the @Default annotation. Beans with the
+@Alternative annotation will only be injected if that particular bean is
+named in the beans.xml file (TODO: add link). Beans with the
+@Specializes annotation will be considered a drop-in replacement for
+it's superclass, and will be used over any implementations it extends. +
+In our case, we'll want to give SimpleGreetingImpl the @Default
+annotation and UserGreetingImpl the @Alternative annotation.
+
+[source,java]
+....
+@Default
+public class SimpleGreetingImpl implements Greeting {
+....
+
+[source,java]
+....
+@Alternative
+public class UserGreetingImpl implements Greeting {
+....
+
+After that the application could actually be deployed. To tell CDI we'll
+want to use our alternative implementation we need to create the
+beans.xml in our WEB-INF folder, and add the following declaration to
+it:
+
+[source,xml]
+....
+<beans>
+ <alternatives>
+ <class>com.vaadin.cdi.tutorial.UserGreetingImpl</class>
+ </alternatives>
+</beans>
+....
+
+Let's try that out:
+
+image:img/hello-stranger.png[Something's not right]
+
+Better, but not quite there yet. We're getting the wrong username,
+despite the fact that we set the username to "Earnest" in the UI. The
+problem here is the scope of the bean. If you don't specify a scope for
+your bean either in the bean class itself or at the injection point,
+it'll default to using the dependent scope. Every time you inject a
+dependent bean you'll get a new instance, which is clearly not what we
+want here. Let's go back to our UserInfo class and assign it an explicit
+scope.
+
+[source,java]
+....
+import com.vaadin.cdi.UIScoped;
+
+@UIScoped
+public class UserInfo {
+...
+....
+
+The @UIScoped annotation is specific to Vaadin CDI. Anything injected
+with that annotation will get the same instance while within the same
+UI. Load a different UI and you'll get a different instance. If the
+session expires or the UI is closed the instances will be cleaned up. +
+Let's see if it worked.
+
+image:img/hello-earnest.png[Something IS right]
+
+Looks like we're making progress.
projects / vaadin-framework.git / commitdiff
