[cdi-dev] [JBoss JIRA] Issue Comment Edited: (CDI-4) Need a way to provide ordering for Event observers (@Observes)

[Christopher Brock (JIRA)]

    [ https://issues.jboss.org/browse/CDI-4?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12600507#comment-12600507 ] 

Christopher Brock edited comment on CDI-4 at 5/7/11 1:10 PM:
-------------------------------------------------------------

After having a conversation with Dan Allen about solving this problem, this is what we came up with.

We propose the addition of two new annotations, @Before and @After which both accept {{Class<? extends Annotation>[]}} to reference qualifiers (one or more).

For example:

*Case A:*
{code}
public class MyBean
	public void myFirstObserver(@Observes @Before(Initialization.class) MyEvent event) {
	   ...
	}

	public void mySecondObserver(@Observes @Initialization MyEvent event) {
	   ...
	} 
}

{code}

*Case B:*
{code}

public class MyBean
	public void myFirstObserver(@Observes @After(Initialization.class) MyEvent event) {
	   ...
	}

	public void mySecondObserver(@Observes @Initialization MyEvent event) {
	   ...
	} 
}
{code}

In Case A, the container would guarantee that when a {{MyEvent}} is fired, that {{myFirstObserver()}} is called before {{mySecondObserver()}}. In Case B, the container would guarantee that {{myFirstObserver()}} is called only _after_ {{mySecondObserver()}} has been called.

In a situation where multiple observers are observing the event with the referenced qualifier, {{@Before}} will indicate the annotated observer shall execute before any of those thus qualified  execute. The converse will be true for {{@After}}.

Where multiple qualifiers are specified in {{@Before}} or {{@After}} the matching behavior will be identical to the dispatch matching behavior of the CDI specification. For instance:

*Case C*
{code}
public void firstObserver(@Observes @A @B @C MyEvent event) { 
}

public void secondObserver(@Observes @A @B @D MyEvent event) { 
}

public void thirdObserver(@Observes @A @E @F @After({A.class, D.class}) MyEvent event) { 
}

{code}

In Case C, {{thirdObserver()}} will only be called after {{secondObserver()}} is called. However, {{firstObserver()}} may be called before or after; the contract with the container does not guarantee any firing order for {{firstObserver()}} relative to the other two observers.

--- 

Also, the specification may benefit from the addition of an {{@OrderingQualifier}} which permits the creation of qualifiers used only for the purpose of ordering, but are otherwise ignored by the container for dispatching of events. This would be optional, of course. Any regular qualifier can be used for ordering. 

Example:
{code}
@OrderingQualifier
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
public @interface MyQualifier {
}
{code}

The presence of ordering qualifiers may muddy the water a little bit in terms of readability. However, I could foresee situations where the use of ordering qualifiers -- when used properly -- could make resolving some complex ordering situations less difficult. At the very least, it would allow for dispatch ordering that could not be circumvented accidentally. And by that I mean, ordering qualifiers cannot be used to qualify event consumers; they are used by the container merely for resolving the dispatch ordering -- which is done when the container bootstraps -- and otherwise have no runtime side-effects. 


      was (Author: cbrock):
    After having a conversation with Dan Allen about solving this problem, this is what we came up with.

We propose the addition of two new annotations, @Before and @After which both accept Class<? extends Annotation>[] to reference qualifiers.

For example:

*Case A:*
{code}
public class MyBean
	public void myFirstObserver(@Observes @Before(Initialization.class) MyEvent event) {
	   ...
	}

	public void mySecondObserver(@Observes @Initialization MyEvent event) {
	   ...
	} 
}

{code}

*Case B:*
{code}

public class MyBean
	public void myFirstObserver(@Observes @After(Initialization.class) MyEvent event) {
	   ...
	}

	public void mySecondObserver(@Observes @Initialization MyEvent event) {
	   ...
	} 
}
{code}

In Case A, the container would guarantee that when a MyEvent is fired, that {{myFirstObserver()}} is called before {{mySecondObserver()}}. In Case B, the container would guarantee that {{myFirstObserver()}} is called only _after_ {{mySecondObserver()}} has been called.

In a situation where multiple observers are observing the event with the referenced qualifier, {{@Before}} will indicate the annotated observer shall execute before any of those thus qualified  execute. The converse will be true for {{@After}}.

Where multiple qualifiers are specified in {{@Before}} or {{@After}} the matching behavior will be identical to the dispatch matching behavior of the CDI specification. For instance:

*Case C*
{code}
public void firstObserver(@Observes @A @B @C MyEvent event) { 
}

public void secondObserver(@Observes @A @B @D MyEvent event) { 
}

public void thirdObserver(@Observes @A @E @F @After({A.class, D.class}) MyEvent event) { 
}

{code}

In Case C, {{thirdObserver()}} will only be called after {{secondObserver()}} is called. However, {{firstObserver()}} may be called before or after; the contract with the container does not guarantee any firing order for {{firstObserver()}} relative to the other two observers.

--- 

Also, the specification may benefit from the addition of an {{@OrderingQualifier}} which permits the creation of qualifiers used only for the purpose of ordering, but are otherwise ignored by the container for dispatching of events. This would be optional, of course. Any regular qualifier can be used for ordering. 

Example:
{code}
@OrderingQualifier
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
public @interface MyQualifier {
}
{code}

The presence of ordering qualifiers may muddy the water a little bit in terms of readability. However, I could foresee situations where the use of ordering qualifiers -- when used properly -- could make resolving some complex ordering situations less difficult. At the very least, it would allow for dispatch ordering that could not be circumvented accidentally. And by that I mean, ordering qualifiers cannot be used to qualify event consumers; they are used by the container merely for resolving the dispatch ordering -- which is done when the container bootstraps -- and otherwise have no runtime side-effects. 

  
> Need a way to provide ordering for Event observers (@Observes)
> --------------------------------------------------------------
>
>                 Key: CDI-4
>                 URL: https://issues.jboss.org/browse/CDI-4
>             Project: CDI Specification Issues
>          Issue Type: Feature Request
>          Components: Events, Portable Extensions
>    Affects Versions: 1.0
>         Environment: All
>            Reporter: Lincoln Baxter III
>            Assignee: Christopher Brock
>             Fix For: TBD
>
>
> There needs to be a way to specify some kind of ordering for Event observers. 
> Understandably, this is somewhat counter-intuitive to the general concept of observing an event, but there is going to be need for this in an upcoming JBoss project. While it can be done manually, it might be nice to have a built-in API.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira