deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gpetra...@apache.org
Subject svn commit: r1555640 - /deltaspike/site/trunk/content/jsf.mdtext
Date Sun, 05 Jan 2014 22:19:57 GMT
Author: gpetracek
Date: Sun Jan  5 22:19:57 2014
New Revision: 1555640

URL: http://svn.apache.org/r1555640
Log:
updated content

Modified:
    deltaspike/site/trunk/content/jsf.mdtext

Modified: deltaspike/site/trunk/content/jsf.mdtext
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/jsf.mdtext?rev=1555640&r1=1555639&r2=1555640&view=diff
==============================================================================
--- deltaspike/site/trunk/content/jsf.mdtext (original)
+++ deltaspike/site/trunk/content/jsf.mdtext Sun Jan  5 22:19:57 2014
@@ -738,8 +738,222 @@ DeltaSpike allows to customize the defau
 It's possible to change it for one usage via `View.basePathBuilder` and/or `View.fileNameBuilder`
and/or `View.extensionBuilder` or globally via the config mechanism provided by DeltaSpike.
 The same is supported for folders via `Folder.DefaultFolderNameBuilder`. In this case changing
only one usage is possible via `Folder.folderNameBuilder`.
 
+# (Grouped-)Conversations
+
+Available with all versions after 0.5.
+
+DeltaSpike conversations are based on the window-scope. Therefore, don't forget to add the
`ds:windowId` (`xmlns:ds="http://deltaspike.apache.org/jsf"`) component in case of ClientWindowConfig#CLIENTWINDOW
to your page(/template) and ensure that the window-handling works properly (otherwise conversations
won't work correctly).
+The base principle is similar to CODI-Conversations. CODI users just have to ensure that
they have to add `ds:windowId` and the names are slightly different.
+
+First of all it's important to mention that DeltaSpike starts (grouped) conversations automatically
as soon as you access conversation scoped beans. Furthermore, the invocation of GroupedConversation#close
leads to an immediate termination of the conversation.
+
+    :::java
+    @GroupedConversationScoped
+    public class DemoBean1 implements Serializable
+    {
+        //...
+    }
+
+... leads to a conversation which contains just one bean with the group DemoBean1.
+
+Hint:
+If you would like to use the bean within your JSF pages, you have to add `@Named` (javax.inject.Named
).
+
+(In case of CDI std. conversations there is just one big conversation which contains all
conversation scoped beans.)
+The grouped conversations provided by DeltaSpike are completely different. By default every
conversation scoped bean exists in an "isolated" conversation. That means there are several
parallel conversations within the same window.
+
+Example - Separated DeltaSpike conversations:
+
+    :::java
+    @GroupedConversationScoped
+    public class DemoBean2 implements Serializable
+    {
+        //...
+    }
+ 
+    @GroupedConversationScoped
+    public class DemoBean3 implements Serializable
+    {
+        //...
+    }
+
+... leads to two independent conversations in the same window (context).
+If you close the conversation of DemoBean2, the conversation of DemoBean3 is still active.
+If you have an use-case (e.g. a wizard) which uses multiple beans which are linked together
very tightly, you can create a type-safe conversation group.
+
+Example - Grouped conversation scoped beans:
+
+    :::java
+    interface Wizard1 {}
+ 
+    @GroupedConversationScoped
+    @ConversationGroup(Wizard1.class)
+    public class DemoBean4 implements Serializable
+    {
+        //...
+    }
+ 
+    @GroupedConversationScoped
+    @ConversationGroup(Wizard1.class)
+    public class DemoBean5 implements Serializable
+    {
+        //...
+    }
+
+You can use `@ConversationGroup` to tell DeltaSpike that there is a logical group of beans.
Technically `@ConversationGroup` is just a CDI qualifier. Internally DeltaSpike uses this
information to identify a conversation. In the previous example both beans exist in the same
conversation (group). If you terminate the conversation group, both beans will be destroyed.
If you don't use `@ConversationGroup` explicitly, DeltaSpike uses the class of the bean as
conversation group.
+
+Example - Injecting a conversation scoped bean with an explicit group:
+
+    :::java
+    //...
+    public class CustomBean1
+    {
+        @Inject
+        @ConversationGroup(Group1.class)
+        private CustomBean2 demoBean;
+ 
+        @Inject
+        @ConversationGroup(Group2.class)
+        private CustomBean2 demoBean;
+    }
+
+Since `@ConversationGroup` is a std. CDI qualifier you have to use it at the injection point.
You have to do that esp. because it's possible to create beans of the same type which exist
in different groups (e.g. via producer methods).
+
+Example - Producer methods which produce conversation scoped beans with different groups:
+
+    :::java
+    interface Group1 {}
+    interface Group2 {}
+ 
+    public class CustomBean2
+    {
+        @Produces
+        @GroupedConversationScoped
+        @ConversationGroup(Group1.class)
+        public CustomBean2 createInstanceForGroup1()
+        {
+            return new CustomBean2();
+        }
+ 
+        @Produces
+        @GroupedConversationScoped
+        @ConversationGroup(Group2.class)
+        public CustomBean2 createInstanceForGroup2()
+        {
+            return new CustomBean2();
+        }
+    }
+
+## Terminating Conversations
+
+You can inject the conversation via `@Inject` and use it to terminate the conversation immediately
or you inject the `GroupedConversationManager` which can be used to terminate a given conversation
(group). All conversations within a window are closed autom., once `WindowContext#closeWindow`
gets called for the window.
+
+Example - Injecting and using the current conversation:
+
+    :::java
+    @GroupedConversationScoped
+    public class DemoBean6 implements Serializable
+    {
+        @Inject
+        private GroupedConversation conversation; //injects the conversation of DemoBean6
(!= conversation of DemoBean7)
+ 
+        //...
+ 
+        public void finish()
+        {
+            this.conversation.close();
+        }
+    }
+ 
+    @GroupedConversationScoped
+    public class DemoBean7 implements Serializable
+    {
+        @Inject
+        private GroupedConversation conversation; //injects the conversation of DemoBean7
(!= conversation of DemoBean6)
+ 
+        //...
+ 
+        public void finish()
+        {
+            this.conversation.close();
+        }
+    }
+
+Example - Injecting and using the explicitly grouped conversation:
+
+    :::java
+    interface Wizard2 {}
+ 
+    @GroupedConversationScoped
+    @ConversationGroup(Wizard2.class)
+    public class DemoBean8 implements Serializable
+    {
+        @Inject
+        private GroupedConversation conversation; //injects the conversation of Wizard2 (contains
DemoBean8 and DemoBean9)
+ 
+        //...
+ 
+        public void finish()
+        {
+            this.conversation.close();
+        }
+    }
+
+    @GroupedConversationScoped
+    @ConversationGroup(Wizard2.class)
+    public class DemoBean9 implements Serializable
+    {
+        @Inject
+        private GroupedConversation conversation; //injects the conversation of Wizard2 (contains
DemoBean8 and DemoBean9)
+ 
+        //...
+ 
+        public void finish()
+        {
+            this.conversation.close();
+        }
+    }
+
+Example - Terminating a grouped conversation outside of the conversation:
+
+    :::java
+    //...
+    public class DemoBean10 implements Serializable
+    {
+        @Inject
+        private GroupedConversationManager conversationManager;
+ 
+        //...
+ 
+        public void finish()
+        {
+            this.conversationManager.closeConversationGroup(Wizard2.class);  //closes the
conversation of group Wizard2.class
+        }
+    }
+
+Example - Terminate all conversations:
+
+    :::java
+    //...
+    public class DemoBean11 implements Serializable
+    {
+        @Inject
+        private GroupedConversationManager conversationManager;
+ 
+        //...
+ 
+        public void finish()
+        {
+            this.conversationManager.closeConversations();  //closes all existing conversations
within the current window (context)
+        }
+    }
+
+Hint:
+DeltaSpike conversations get closed/restarted immediately instead of keeping them until the
end of the request like std. conversations do, because the behaviour of std. conversations
breaks a lot of use-cases. However, if you really need to keep them until the end of the request,
you can close them in a @PostRenderView callback.
+
+
 # Support of EAR deployments
 Before using features described by this page, please ensure that you are aware of [DELTASPIKE-335](https://issues.apache.org/jira/browse/DELTASPIKE-335)
and the corresponding impact.
 
 # Hints
-Using errorView, DefaultErrorView or ViewNavigationHandler will fail with Weld versions below
1.1.10 due to [WELD-1178](https://issues.jboss.org/browse/WELD-1178).
\ No newline at end of file
+Using errorView, DefaultErrorView or ViewNavigationHandler will fail with Weld versions below
1.1.10 due to [WELD-1178](https://issues.jboss.org/browse/WELD-1178).



Mime
View raw message