Return-Path: X-Original-To: apmail-openejb-commits-archive@www.apache.org Delivered-To: apmail-openejb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 157967760 for ; Tue, 1 Nov 2011 04:01:05 +0000 (UTC) Received: (qmail 60398 invoked by uid 500); 1 Nov 2011 04:01:05 -0000 Delivered-To: apmail-openejb-commits-archive@openejb.apache.org Received: (qmail 60380 invoked by uid 500); 1 Nov 2011 04:01:04 -0000 Mailing-List: contact commits-help@openejb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@openejb.apache.org Delivered-To: mailing list commits@openejb.apache.org Received: (qmail 60373 invoked by uid 99); 1 Nov 2011 04:01:04 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 01 Nov 2011 04:01:04 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 01 Nov 2011 04:01:01 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 41BCF2388A9B for ; Tue, 1 Nov 2011 04:00:11 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r797834 - in /websites/staging/openejb/trunk/content: dev/ examples-trunk/ examples-trunk/cdi-alternative-and-stereotypes/ examples-trunk/cdi-events/ examples-trunk/cdi-events/src/ examples-trunk/cdi-events/src/main/ examples-trunk/cdi-even... Date: Tue, 01 Nov 2011 04:00:10 -0000 To: commits@openejb.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20111101040011.41BCF2388A9B@eris.apache.org> Author: buildbot Date: Tue Nov 1 04:00:09 2011 New Revision: 797834 Log: Staging update by buildbot Added: websites/staging/openejb/trunk/content/dev/writing-examples.html websites/staging/openejb/trunk/content/examples-trunk/cdi-events/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/README.html websites/staging/openejb/trunk/content/examples-trunk/cdi-events/pom.xml websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/superbiz/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/superbiz/cdi/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/superbiz/cdi/events/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/superbiz/cdi/events/Notifier.java websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/resources/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/resources/META-INF/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/resources/META-INF/beans.xml websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/EventTest.java websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/Observer.java websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/META-INF/ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/META-INF/beans.xml websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/log4j.xml Modified: websites/staging/openejb/trunk/content/examples-trunk/cdi-alternative-and-stereotypes/README.html websites/staging/openejb/trunk/content/examples-trunk/pom.xml Added: websites/staging/openejb/trunk/content/dev/writing-examples.html ============================================================================== --- websites/staging/openejb/trunk/content/dev/writing-examples.html (added) +++ websites/staging/openejb/trunk/content/dev/writing-examples.html Tue Nov 1 04:00:09 2011 @@ -0,0 +1,198 @@ + + + + + + Writing Examples + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ Apache TomEE + + + +
+ + + +
+ + +
+
+
+ +
+ + + +
+Home » Dev
+

Writing Examples

+
+ +

Some basic guideliness of writing examples:

+ +
    +
  • focus on one idea per example
    • +
  • keep examples short +
      +
    • one test case
      • +
    • minimal code to make the point
      • +
    • +
  • avoid showing an entire API in one example, if possible
    • +
  • be concious of the cost of "setting the stage"
    • +
  • if examples get too big, split it
    • +
+ +

Noise vs signal

+ +

Example scenarios do not need to be believable and should not be elaborate. Get to the point in as few classes as possible.

+ +

You should be able to explain the entire example in two minutes.

+ +

5 was to do the same thing

+ +

It takes time to learn the example scenario. Be very mindful of that.

+ +

If there are five ways to do the same thing, avoid making 5 different different scenarios. Copy the example to a new directory, and tweak it to show the variation.

+ +

So say you used objects Green, Square and Checkers to show the basic concept and you wish to show the next variation of that same concecpt. It is tempting to add to the same +example objects Yellow, Triangle and PolkaDots.

+ +

Avoid that. Copy Green, Square and Checkers to a new example, change the package name, and update the few lines needed to show the difference.

+ +

Which is easier to learn?

+ +
    +
  • 934 + 55 = 989
    • +
  • 513 - 19 = 494
    • +
  • 468 * 44 = 20592
    • +
  • 708 / 89 = 7
    • +
  • 401 % 63 = 23
    • +
+ +

Or:

+ +
    +
  • 102 + 35 = 137
    • +
  • 102 - 35 = 67
    • +
  • 102 * 35 = 3570
    • +
  • 102 / 35 = 2
    • +
  • 102 % 35 = 32
    • +
+ +

When presenting, you only get so much time to show people ideas. If they have to learn a new set of names and understand their relationship on each tiny variation, it severely +impacts their ability to see what is supposed to be the same and what is supposed to be different. As a presenter this means you must show less and what you do show will be shown +less clearly.

+ +

When names and scenarios are consistent, the variations jump out quickly and with impact.

+ +

If there are five ways to do the same thing, show the same thing five different ways.

+ +

Short Class Names

+ +

You don't need to document the example with the class name. Class names that are a mouthful cannot be effectively used in presentations or screencasts.

+ +

Try to stick with one or two word class names. Three tops.

+ +

Avoid:

+ +
    +
  • BeanWithTwoDecoratorsAndOneProducerMethod
    • +
+ +

Try instead:

+ +
    +
  • BlueBean
    • +
+ +

Shorter names can be easier for all sorts of reasons. Less words to keep "floating in the head" when trying to truly see an example.

+ +

Using the numbers from the previous section, which is easier?

+ +
    +
  • 102 + 35 = 137
    • +
  • 102 - 35 = 67
    • +
  • 102 * 35 = 3570
    • +
  • 102 / 35 = 2
    • +
  • 102 % 35 = 32
    • +
+ +

Or:

+ +
    +
  • 12 + 3 = 15
    • +
  • 12 - 3 = 9
    • +
  • 12 * 3 = 36
    • +
  • 12 / 3 = 4
    • +
  • 12 % 3 = 0
    • +
+ +

There's a finite amount people can keep in their head, save space for the important stuff.

+ + + + +
+

+ Copyright © 2011 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache and the Apache feather logo are trademarks of The Apache Software Foundation. +

+
+ +
+ + + + + + + + Modified: websites/staging/openejb/trunk/content/examples-trunk/cdi-alternative-and-stereotypes/README.html ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-alternative-and-stereotypes/README.html (original) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-alternative-and-stereotypes/README.html Tue Nov 1 04:00:09 2011 @@ -140,10 +140,12 @@ public @interface Mock {}

So now we have our @Mock annotation which is a stereotype able to replace @Alternative annotation we simply add this annotation to our mocks.

-

If you run it now you'll have this exception: - javax.enterprise.inject.UnsatisfiedResolutionException: Api type [org.superbiz.cdi.stereotype.Vehicle] is not found with the qualifiers - Qualifiers: [@javax.enterprise.inject.Default()] - for injection into Field Injection Point, field name : vehicle, Bean Owner : [Journey, Name:null, WebBeans Type:ENTERPRISE, API Types:[java.lang.Object,org.superbiz.cdi.stereotype.Journey], Qualifiers:[javax.enterprise.inject.Any,javax.enterprise.inject.Default]]

+

If you run it now you'll have this exception:

+ +
javax.enterprise.inject.UnsatisfiedResolutionException: Api type [org.superbiz.cdi.stereotype.Vehicle] is not found with the qualifiers
+Qualifiers: [@javax.enterprise.inject.Default()]
+for injection into Field Injection Point, field name :  vehicle, Bean Owner : [Journey, Name:null, WebBeans Type:ENTERPRISE, API Types:[java.lang.Object,org.superbiz.cdi.stereotype.Journey], Qualifiers:[javax.enterprise.inject.Any,javax.enterprise.inject.Default]]
+

It means the stereotype is not activated. To do it simply add it to your META-INF/beans.xml:

Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/README.html ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/README.html (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/README.html Tue Nov 1 04:00:09 2011 @@ -0,0 +1,144 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ Apache TomEE + + + +
+ + + +
+ + +
+
+
+ +
+ + + +
+
+ Home » Examples Trunk » Cdi Events
+
+
+
+ download example +
+
+
+ +
+

+
+ +

CDI events: loose coupling and extensibility

+ +

CDI allows you to extend business code by the Notifier/Observer pattern.

+ +

To do it you simply inject a field Event in the notifier class. This class is a template +and the parameter type is the object type to fire. Then when you want to notify observers +you simply call the method fire of the event object passing as a parameter the event itself +(your own class!).

+ +

On the other side you annotated a method parameter @Observes and the parameter type is the sent type +by the notifier.

+ +

Note: of course you can add qualifiers to be more precise on your events.

+ +

The example

+ +

The example is pretty simple: an ejb uses the @Schedule annotation to get a notification each second. +The each second this EJB will send the current date through CDI events.

+ +

This is our "business" code. It is a simple behavior (nothing).

+ +

In our test (which is considered as an extension) we created an observer (Observer class) +which simply store and log each received date.

+ +

The test itself (EventTest) simply verifies the dates were received.

+ +

Conclusion

+ +

CDI let's implement very easily plugins through this event mecanism.

+ +

If you go further and look at CDI plugin API you'll realize it is simply the same kind +of events. CDI events is really the basis of CDI.

+ + +
 
+

APIs Used

+ + + + +
+

+ Copyright © 2011 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache and the Apache feather logo are trademarks of The Apache Software Foundation. +

+
+ +
+ + + + + + + + Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/pom.xml ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/pom.xml (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/pom.xml Tue Nov 1 04:00:09 2011 @@ -0,0 +1,111 @@ + + + + + + + 4.0.0 + org.superbiz + cdi-events + jar + 1.1-SNAPSHOT + OpenEJB :: Examples :: CDI Events + + UTF-8 + + + install + + + org.apache.maven.plugins + maven-compiler-plugin + 2.3.2 + + 1.6 + 1.6 + + + + + + + apache-m2-snapshot + Apache Snapshot Repository + http://repository.apache.org/snapshots + + + + + org.apache.openejb + javaee-api + 6.0-3-SNAPSHOT + provided + + + junit + junit + 4.8.1 + test + + + + org.apache.openejb + openejb-core + 4.0.0-beta-2-SNAPSHOT + test + + + + org.slf4j + slf4j-log4j12 + 1.6.1 + test + + + org.slf4j + slf4j-api + 1.6.1 + test + + + log4j + log4j + 1.2.16 + test + + + + + + localhost + file://${basedir}/target/repo/ + + + localhost + file://${basedir}/target/snapshot-repo/ + + + Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/superbiz/cdi/events/Notifier.java ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/superbiz/cdi/events/Notifier.java (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/java/org/superbiz/cdi/events/Notifier.java Tue Nov 1 04:00:09 2011 @@ -0,0 +1,36 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.superbiz.cdi.events; + +import javax.ejb.Schedule; +import javax.ejb.Singleton; +import javax.enterprise.event.Event; +import javax.inject.Inject; +import java.util.Date; + +/** + * @author rmannibucau + */ +@Singleton +public class Notifier { + @Inject private Event dateEvent; + + @Schedule(second = "*", minute = "*", hour = "*") + public void sendHour() { + dateEvent.fire(new Date()); + } +} Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/resources/META-INF/beans.xml ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/resources/META-INF/beans.xml (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/main/resources/META-INF/beans.xml Tue Nov 1 04:00:09 2011 @@ -0,0 +1,5 @@ + + Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/EventTest.java ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/EventTest.java (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/EventTest.java Tue Nov 1 04:00:09 2011 @@ -0,0 +1,75 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.superbiz.cdi.events; + +import org.junit.After; +import org.junit.AfterClass; +import org.junit.Before; +import org.junit.BeforeClass; +import org.junit.Test; + +import javax.ejb.embeddable.EJBContainer; +import javax.inject.Inject; +import javax.naming.NamingException; + +import static junit.framework.Assert.assertTrue; + +/** + * @author rmannibucau + */ +public class EventTest { + private static EJBContainer container; + private static String initialLogProperty; + + @Inject + private Observer observer; + + @BeforeClass + public static void start() throws NamingException { + initialLogProperty = System.getProperty("openejb.logger.external"); + System.setProperty("openejb.logger.external", "true"); + container = EJBContainer.createEJBContainer(); + } + + @AfterClass + public static void shutdown() { + if (container != null) { + container.close(); + } + if (initialLogProperty != null) { + System.setProperty("openejb.logger.external", initialLogProperty); + } else { + System.getProperties().remove("openejb.logger.external"); + } + } + + @Before + public void inject() throws NamingException { + container.getContext().bind("inject", this); + } + + @After + public void reset() throws NamingException { + container.getContext().unbind("inject"); + } + + @Test + public void observe() throws InterruptedException { + Thread.sleep(4000); + assertTrue(observer.getDates().size() > 3); // in 4s normally at least 3 events were received + } +} Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/Observer.java ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/Observer.java (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/java/org/superbiz/cdi/events/Observer.java Tue Nov 1 04:00:09 2011 @@ -0,0 +1,45 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.superbiz.cdi.events; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import javax.enterprise.event.Observes; +import javax.inject.Singleton; +import java.util.ArrayList; +import java.util.Date; +import java.util.List; + +/** + * @author rmannibucau + */ +@Singleton +public class Observer { + private static final Logger LOGGER = LoggerFactory.getLogger(Observer.class); + + private List dates = new ArrayList(); + + public void saveDate(@Observes Date date) { + dates.add(date); + LOGGER.info("received date '{}'", date); + } + + public List getDates() { + return dates; + } +} Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/META-INF/beans.xml ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/META-INF/beans.xml (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/META-INF/beans.xml Tue Nov 1 04:00:09 2011 @@ -0,0 +1,5 @@ + + Added: websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/log4j.xml ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/log4j.xml (added) +++ websites/staging/openejb/trunk/content/examples-trunk/cdi-events/src/test/resources/log4j.xml Tue Nov 1 04:00:09 2011 @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + Modified: websites/staging/openejb/trunk/content/examples-trunk/pom.xml ============================================================================== --- websites/staging/openejb/trunk/content/examples-trunk/pom.xml (original) +++ websites/staging/openejb/trunk/content/examples-trunk/pom.xml Tue Nov 1 04:00:09 2011 @@ -17,7 +17,7 @@ limitations under the License. --> - + @@ -90,6 +90,7 @@ cdi-produces-disposes dynamic-implementation cdi-alternative-and-stereotypes + cdi-events