See the previous articles:
Use dynamic proxies to create a simple, powerful event bus (Part 1)
Use dynamic proxies to create a simple, powerful event bus (Part 2)

Using the event bus

If you’ve followed along with the previous event bus blogs, you already know what I mean by simple – simple to use. We want an event bus that doesn’t require a fleet of event classes or fireXXX methods.

1
2
3
4
5
6
7
8
9
10
11
12

EventBus eventBus = new EventBus();
 
// Listen for newSearch events
eventBus.addListener(SearchListener.class, new SearchListener(){
	public void newSearch(String query) {
		System.out.println("Searching for " + query);
	}
});
 
// Publish newSearch event
SearchListener publisher = eventBus.getPublisher(SearchListener.class);
publisher.newSearch("GWT event bus");

We want to call a method, like newSearch("GWT event bus"), and have it automatically invoked on all observers as if we’d called each one ourselves. We want method multicasting. As you can see in the code above, we use the same SearchListener interface to both observe newSearch events and publish them.

GWT generators

In the original event bus we used reflection, specifically, we used Java’s dynamic proxies to accomplish the publisher-listener magic. GWT doesn’t have anything like this, but it does provide hooks into the compiler for code generators. Basically, we can generate the publisher code at compile to perform the same function dynamic proxies did at runtime.

Code generation happens (it seems) during GWT’s precompile phase. The actual compiler hook is triggered by a combination of a GWT.create() call in the Java source and a generate-with element in the GWT module XML file. The GWT.create method takes a class literal to instantiate – GWT.create(PublisherFactoryRegistry.class) in this case. The generate-with element tells the compiler that EventPublisherGenerator will create the Java source that extends (or implements if it were an interface) PublisherFactoryRegistry.

1
2
3

<generate-with class="com.northconcepts.eventbus.generator.EventPublisherGenerator">
    <when-type-assignable class="com.northconcepts.eventbus.client.PublisherFactoryRegistry" />
</generate-with>

The compiler treats the Java source emitted by EventPublisherGenerator like any other class and optimizes it, converts it to JavaScript, obfuscates it, etc. GWT.create then returns an instance of the generated class to its caller. Google calls this whole process Deferred Binding using Generators.

For more details on the GWT compiler, watch Ray Cromwell’s Optimizing apps with the GWT Compiler session at Google I/O.

Event bus changes

GWT is a special variant of Java and not everything from standard Java is available (primarily because GWT only supports what can be emulated in JavaScript). I mentioned before that reflection and dynamic proxies are not available, here are a few more differences you’ll want to note when comparing the code here with the pure Java event bus:

1. JavaScript is single-threaded so we don’t have to worry about threading or synchronization for the most part.
2. No threading also means no executor service, but we’ll use deferred (or scheduled) commands to simulate it.
3. Thread-locals are also out.
4. While JavaScript uses a garbage collector, we don’t have the same hooks into it as we do in Java. This means no soft references and no automatic releasing of observers.

EventBus.getPublisher() changes

1
2
3
4
5
6
7
8
9
10

public <T extends EventListener> T getPublisher(Object eventSource, 
Class<T> eventListenerClass, Object topic) {
    T publisher = PUBLISHER_FACTORIES.getPublisher(eventListenerClass);
    EventPublisher<T> publisher2 = (EventPublisher<T>) publisher;
    publisher2.setEventBus(this);
    publisher2.setEventSource(eventSource);
    publisher2.setEventListenerClass(eventListenerClass);
    publisher2.setTopic(topic);
    return publisher;
}

The old, pure Java getPublisher method would implement the listener interface using a dynamic proxy. The proxy would publish events to the bus whenever called. This new GWT event bus keeps a registry of factories to create publishers that implement each type of event listener interface. Publishers also extend the EventPublisher class which allows getPublisher to initialize them with the event source, topic, etc. Like the non-GWT version, publishers queue events to the bus when called.

EventBus.publishEvent() changes

1
2
3
4
5
6
7
8
9
10
11
12
13
14

protected <T extends EventListener> void publishEvent(
final Event<T> event) {
    Scheduler.get().scheduleDeferred(new ScheduledCommand() {
        @Override public void execute() {
            try { 
                deliverEvent(event); 
            } catch (RuntimeException e) { 
                throw e; 
            } catch (Throwable e) { 
                throw new RuntimeException(e.getMessage(), e); 
            } 
        } 
    });
}

The only change to publishEvent is in how it schedules event delivery. The new method uses GWT’s scheduler service (formerly called deferred commands) since executor services are not supported.

EventBus.deliverEvent() changes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

protected <T extends EventListener> void deliverEvent(Event<T> event)
throws Throwable {
    try {
        currentEvent = event;
        // Deliver to typed listeners
        TypedListenerList<T> list = getTypedListenerList(
        event.getEventListenerClass());
        if (list != null) {
            for (EventListenerStub<?> stub : list.getList()) {
                stub.deliverEvent(this, event);
            }
        }
        // Deliver to untyped listeners
        for (EventListenerStub<UntypedEventListener> stub : 
        untypedListeners) {
            stub.deliverEvent(this, event);
        }
    } finally {
        currentEvent = null;
    }
}

Changes to deliverEvent are also minimal. The cleanupGarbage() call is removed since we don’t have soft references to clean up and currentEvent is demoted from a thread-local to just an instance field.

Generated code

Let’s take a look at the code we need to generate. Here we produce two kinds of classes: a event publisher for each event listener and one PublisherFactoryRegistry implementation to hold the publisher factories.

Event publishers

Publishers implement the event listener interfaces, convert method calls into events, and publishes the events to the bus.

1
2
3
4
5

public interface SearchListener extends EventListener {
    void newSearch(String query); 
    void searchFinished(String query, ArrayList<Data> results); 
    void detailsViewed(Data data); 
}

The code generator seeing the above SearchListener interface will create the following SearchListener__publisher class. Each implemented method creates an event object containing things you’d expect like event source, topic, and arguments. Since we don’t have reflection, the event object also contains an EventDispatcher to invoke the observer’s method when directed to do so by the bus.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class SearchListener__publisher 
extends EventPublisher implements SearchListener {
  ...
  public void searchFinished(final String query, 
  final ArrayList results) {
    publishEvent(new Event<SearchListener>(
    getEventSource(), 
    this, 
    SearchListener.class, 
    getTopic(), 
    "searchFinished", 
    new String[]{"query", "results"}, 
    new String[]{"java.lang.String", "java.util.ArrayList"}, 
    new Object[]{query, results}, 
    new EventDispatcher<SearchListener>(){
      public void dispatch(SearchListener listener) {
        listener.searchFinished(query, results);
      }
    }));
  }
  ...
}

Publisher factory registry

1
2
3
4
5
6
7
8
9

public class PublisherFactoryRegistryImpl 
extends PublisherFactoryRegistry {
  {
    ...
    publishers.put(SearchListener.class, new EventPublisherFactory() {
        public SearchListener create() {
            return new SearchListener__publisher();}});
  }
}

The PublisherFactoryRegistry class is used by the bus to find factories that create publishers (like SearchListener__publisher). The concrete PublisherFactoryRegistryImpl we generate is only there to register a factory for each publisher we generate — by putting it into the publishers HashMap.

Preserving the generated code

You can tell the GWT compiler to keep the generated Java code around for you to review. Just add the -gen folder compiler flag, where folder is the path to generate temporary files.

The Code Generator

The contract for GWT code generators is to extend com.google.gwt.core.ext.Generator and implement its generate(TreeLogger logger, GeneratorContext context, String typeName) method. The implemented method should return the name of the generated subclass for the type passed into GWT.create. As you review the code, you’ll notice that we’ve added several helper classes (ClassDeclaration, ClassBuilder, CSV, etc.) to make the code less verbose.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

public class EventPublisherGenerator extends Generator {
 
  private TreeLogger logger;
  private GeneratorContext context;
  private TypeOracle typeOracle;
  private JClassType type;
  private JClassType eventListenerType;
  private JClassType eventType;
  private JClassType eventDispatcherType;
  private JClassType eventPublisherType;
  private JClassType eventPublisherFactoryType;
 
  @Override
  public String generate(TreeLogger logger, GeneratorContext context, String typeName) throws UnableToCompleteException {
    try {
      init(logger, context, typeName);
      return generate();
    } catch (Throwable e) {
      logger.log(TreeLogger.ERROR, "generate failed: " + typeName, e);
      throw new UnableToCompleteException();
    }
  }
 
  private void init(TreeLogger logger, GeneratorContext context, String typeName) throws Throwable {
    this.logger = logger;
    this.context = context;
    this.typeOracle = context.getTypeOracle();
    this.type = typeOracle.getType(typeName);
    this.eventListenerType = typeOracle.getType(EventListener.class.getName());
    this.eventType = typeOracle.getType(Event.class.getName());
    this.eventDispatcherType = typeOracle.getType(EventDispatcher.class.getName());
    this.eventPublisherType = typeOracle.getType(EventPublisher.class.getName());
    this.eventPublisherFactoryType = typeOracle.getType(EventPublisherFactory.class.getName());
  }

We’ve created an init method to act as a poor man’s constructor for the generator. It uses the compiler’s metadata registry (TypeOracle) to lookup several classes we’ll need later.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

private String generate() throws Throwable {
  final ClassDeclaration clazz = new ClassDeclaration(
      type.getPackage().getName(), 
      type.getSimpleSourceName() + "Impl", 
      type.getQualifiedSourceName());
 
  final ClassBuilder classBuilder = new ClassBuilder(logger, context, clazz);
  if (classBuilder.classAlreadyExists()) {
    return classBuilder.commit();
  }
 
  classBuilder.println("{");
  classBuilder.indent();
 
  visitEventListeners(logger.branch(TreeLogger.TRACE, "Event listeners"), new ClassVisitor() {
    @Override
    public void visitClass(JClassType eventListenerType) {
      String name = createPublisher(eventListenerType);
      if (name != null) {
        classBuilder.println("publishers.put(%1$s.class, new %2$s() {public %1$s create() {return new %3$s();}});", 
            eventListenerType.getQualifiedSourceName(), 
            eventPublisherFactoryType.getQualifiedSourceName(),
            name);
      }
    }
  });
 
  classBuilder.outdentln("}");
 
  return classBuilder.commit();
}

The no-arg generate method is where the work starts. Here we create the PublisherFactoryRegistryImpl class and give it an instance initializer where the factories are registered. We also call createPublisher() to generate the code for the publisher implementation for each EventListener sub-interface. The visitor pattern is used here to let us focus on code generation while delegating the EventListener finder logic to visitEventListeners().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

private void visitEventListeners(TreeLogger logger, ClassVisitor visitor) {
  FIND_CANDIDATES_LOOP: 
  for (JClassType type : typeOracle.getTypes()) {
    if (type.isInterface() != null && type.isAssignableTo(eventListenerType) && !type.equals(eventListenerType)) {
 
      if (type.isParameterized() != null) {
        logger.branch(TreeLogger.WARN, type.getQualifiedSourceName() + " - skipped - is parameterized type").log(
            TreeLogger.WARN, type.getParameterizedQualifiedSourceName());
        continue FIND_CANDIDATES_LOOP;
      }
 
      for (JMethod method : type.getMethods()) {
        if (!method.getReturnType().equals(JPrimitiveType.VOID)) {
          logger.branch(TreeLogger.WARN, type.getQualifiedSourceName() + " - skipped - has method that returns non-void")
              .log(TreeLogger.WARN, method.getReadableDeclaration());
          continue FIND_CANDIDATES_LOOP;
        }
      }
 
      logger.log(TreeLogger.INFO, type.getQualifiedSourceName());
      visitor.visitClass(type);
    }
  }
}

The visitEventListeners method looks for types the compiler knows about that match the following criteria:

1. are interfaces
2. are not parameterized (like a java.util.List)
3. extend java.util.EventListener
4. have only void returning methods

The visitor’s visitClass method is called for matches, while partial matches emit a compiler warning along with the reason for the mismatch.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

private String createPublisher(JClassType eventListenerType) {
  ClassDeclaration clazz = new ClassDeclaration(
      eventListenerType.getPackage().getName(), 
      eventListenerType.getName() + "__publisher", 
      eventPublisherType.getQualifiedSourceName());
 
  clazz.addImplementedInterface(eventListenerType.getQualifiedSourceName());
 
  ClassBuilder classBuilder = new ClassBuilder(logger, context, clazz);
  if (classBuilder.classAlreadyExists()) {
    return classBuilder.commit();
  }
 
  for (JMethod method : eventListenerType.getMethods()) {
    CSV paramerNames = new CSV();
    CSV paramerTypeNames = new CSV();
    CSV arguments = new CSV();
    final JParameter[] parameters = method.getParameters();
    final boolean hasParameters = parameters.length > 0;
 
    for (int i = 0; i < parameters.length; i++) {
      JParameter parameter = parameters[i];
      paramerNames.add("\"" + parameter.getName() + "\"");
      paramerTypeNames.add("\"" + MethodDeclaration.getParameterTypeName(method, i) + "\"");
      arguments.add(parameter.getName());
    }
 
    classBuilder.startMethod(new MethodDeclaration(method));
 
    classBuilder.println("publishEvent(new %1$s<%2$s>(", 
        eventType.getQualifiedSourceName(), 
        eventListenerType.getQualifiedSourceName());
 
 
    classBuilder.println("getEventSource(), ");
    classBuilder.println("this, ");
    classBuilder.println("%1$s.class, ", eventListenerType.getQualifiedSourceName());
    classBuilder.println("getTopic(), ");
    classBuilder.println("\"%1$s\", ", method.getName());
    if (hasParameters) {
      classBuilder.println("new String[]{%1$s}, ", paramerNames);
      classBuilder.println("new String[]{%1$s}, ", paramerTypeNames);
      classBuilder.println("new Object[]{%1$s}, ", arguments);
    } else {
      classBuilder.println("null, null, null, ");
    }
    classBuilder.println("new %1$s<%2$s>(){", 
        eventDispatcherType.getQualifiedSourceName(), 
        eventListenerType.getQualifiedSourceName());
 
    classBuilder.indentln("public void dispatch(%1$s listener) {", eventListenerType.getQualifiedSourceName());
    classBuilder.indentln("listener.%1$s(%2$s);", method.getName(), (hasParameters?arguments:""));
    classBuilder.outdentln("}");
    classBuilder.outdentln("}));");
 
    classBuilder.endMethod();
  }
 
  return classBuilder.commit();
}

This lengthy method creates the publisher implementation. It implements each method in the event listener interface to publish its description and payload as an event to the bus.

Example

The downlad for this blog includes a simple search example to demonstrate using the event bus. You can run the EventBusExample module (/src/com/northconcepts/eventbusexample/EventBusExample.gwt.xml) or try out the precompiled app by browsing to WebContent/index.html.

The app has four display areas that plug into the event bus:

1. SearchUI- accepts user input and starts the search
2. ResultsUI – holds search results and handles clickfor full details
3. DetailsUI- shows full details when result is clicked
4. StatusUI – shows search progress and results summary.

The actual search function is performed by a non-visual component called SearchEngine. Like the display areas, it also plugs into the bus to both observer and publish events.

When the user fills in the text field and presses the search button, the SearchUI publishes a newSearch event to the bus. The SearchEngine receives the notification and runs the search. The StatusUI also receives the notification and displays a search-in-progress message to the user.

When the search is complete, SearchEngine publishes a searchFinished message to the bus. The ResultsUI receives the notification and displays the data, if any, in a table to the user. The StatusUI also receives the notification and displays to the user either a message with the number of results found or a message that none were found.

If results were found, the user can click one of the items in the ResultsUI which will publish a detailsViewed event. The DetailsUI will receive this event and display all the data for the selected record.

Conclusion

While GWT doesn’t support Java reflection, it does provide a powerful code generation facility. Code generation has the benefit of enabling dynamic, reflexive programming without the runtime cost. Once you get used to GWT’s approach, you’ll start seeing many opportunities to reduce your code size by leveraging GWT’s generators.

Download

The event bus download contains the entire source code (including Eclipse project). The source code is licensed under the terms of the Apache License, Version 2.0.

Often in production environments, configuration is isolated as files on the local disk, limiting easy access by all but administrators.  Another common approach is to store configuration in a database or LDAP.  While this have benefits of a local disk file, it lacks the ability to manage properties as naturally as a file.

The solution proposed uses a database and WebDAV to help resolve many negatives to do with application configuration in both a simple and lightweight way.

In the first blog in the WebDAV series, we discussed a simple example of how you can use WebDAV to create an online network drive, to illustrate how WebDAV can quickly enhance your application. I recommend reading it first before moving onto this blog.

Solution Features

We can help resolve those pains and have added benefits just by using a database and WebDAV. This approach allows for accessibility (both read & read/write) for a larger set of user types, and allows those users the ability to:

• view and edit individual properties from their favorite text editor
• backup & restore property files quickly, by just zipping them up for example
• migrate property files from one environment to another by copying over a folder

All this is packaged as a simple add-on that can be quickly integrated to your existing web application.

Design

File & Folder Structure

This is an example of how the mapped drive would appear when mounted:

Schema

Below is the simple schema that is used:

Properties to File and File to Properties Transformation

To keep things simple and consistent, we use the existing methods present in the Properties class to generate a file from properties and vice versa.  By using this method, properties appear in the file content as key-value pairs, one per line separated by ‘=’ as you commonly see String properties represented.

Usage

Of course, having your application read these properties is vital.  To that effect, there is a class called WebDAVProperties where your application can both read and write properties:

Properties WebDAVProperties.getProperties(String path) where path is the fully qualified path of the properties resource.

void WebDAVProperties.saveProperties(String path, Properties props) where path is the fully qualified path of the properties resource.

Saving the properties using the above method calls the necessary DAOs to persist the properties in the schema.

Implementation

Class Diagram

Model Objects

There are 2 model objects in use in this approach (besides the java.util.Properties object). Both are under the package com.northconcepts.webdav.model.

DAO

Under the package com.northconcepts.webdav.dao you will see 3 DAO classes: FileDAO, FolderDAO, and PropertyDAO.

FileDAO

• List<FileInfo> getFilesInFolder(FolderInfo fi) – gets the list of files that are in the specified folder

FolderDAO

• FolderInfo getFolderById(final int id) – gets the folder by it’s id
• FolderInfo getParentFolder(final FolderInfo f) – gets the parent folder by the provided folder’s id
• List<FolderInfo> getSubFolders(final FolderInfo id) – gets the subfolders by the provided folder’s id
• FolderInfo createFolder(final String name, final FolderInfo parentFolder) – persists a folder based on the specified values and returns that folder
• void deleteFolder(final int id) – deletes the folder by it’s id
• void moveFolder(final int id, final int destFolderId, final String name) – moves the folder of the specified id to below the specified destination folder id and rename the folder to the new name

PropertyDAO

• Properties getProperties(final int fileId) – gets all the property key-value pairs for the given file’s id
• FileInfo createProperties(final String name, final Properties props, final FolderInfo folder) – persists a properties based on the specified key-value pairs, name and folder location

WebDAV Implementation

For a simple Milton Java WebDAV Server Library in-memory implementation example with just a single file and no folders, please review the previous blog post. Similar to the aforementioned model objects, we have 2 classes implementing the various WebDAV Resource interfaces: DavFolder and DavFile.

WebDAV Resource Interfaces

Key to this part of the implementation is understand the behavior implications by implementing specific Resource interfaces.

• GetableResource – allows the content of the resource can be retrieved
• DeletableResource – allows the resource to be deleted
• CollectionResource – the resource to have children implying the directory behavior
• PutableResource – allows file resources to be created as children below it
• MakeCollectionableResource – allows folder resources to be created as children below it
• MoveableResource – allows the resource to be moved to a child of another folder

Properties Processing

Since we want to be able to read the contents of a file as well as delete the file, we need to implement the interfaces GetableResource and DeletableResource.
Below is the sendContent(...) method of the DavFile class, required by the GetableResource interface:

public void sendContent(OutputStream out, Range range, Map params, String contentType) throws IOException, NotAuthorizedException, BadRequestException {
	PrintStream ps = new PrintStream(out);
	p.getProps().list(ps);
	ps.flush();
}

This method is using the existing list method of the Properties class to render the content of the file.
The opposing act of persisting properties by file creation, that is driven by the createNew(...) method of the DavFolder class:

public com.bradmcevoy.http.Resource createNew(String name, InputStream is, Long length, String contentType) throws IOException, ConflictException, NotAuthorizedException, BadRequestException {
	log.debug("attempting to create a new file in this folder name={} length={} contentType={}",new Object[]{name,length,contentType});
 
	//CHECK IF INVALID NAME
	if (Util.isEmpty(name)) {
		log.error("bad request when creating a file");
		throw new BadRequestException(this);
	}
 
	//ASSERT NO CONFLICT WITH THE NAME
	assertNoConflict(name);
 
	//LOAD STREAM TO A PROPERTIES OBJECT
	Properties p = new Properties();
	p.load(is);
 
	//PERSIST THE PROPERTIES AND RETURN THE DAV-WRAPPED NCPROPERTIES
	return new DavFile(PropertyDAO.createProperties(name,p,f));
}

Once again we are using a provided method in the Properties class to parse and load the properties coming from the input stream.

MyResourceFactory Implementation

Finally, to be able to produce the file system structure as designed, the class implementing the ResourceFactory uses recursion to determine, based on the path, whether to offer back a appropriate folder, or the appropriate file.

public class MyResourceFactory implements ResourceFactory {
 
	private static final Logger log = LoggerFactory.getLogger(MyResourceFactory.class);
 
	@Override
	public Resource getResource(String host, String strPath) {
		Path path = Path.path(strPath);
		log.debug("getting resource - host={} path={}",host,path);
 
		//STRIP PRECEEDING PATH
		path = path.getStripFirst().getStripFirst();
		log.debug("path trimmed - new webdav parts={}",path.getParts());
 
		if (path.isRoot()) {
			log.debug("path is just the root, returning the Root Folder");
			return new DavFolder(FolderDAO.getRootFolder());
		} else {
			return recursePath(path, FolderDAO.getRootFolder());
		}
	}
 
	private Resource recursePath(Path path, FolderInfo parentFolder) {
		log.debug("recursing path - path={} parentFolder={}",path,parentFolder);
		for (FolderInfo f : FolderDAO.getSubFolders(parentFolder)) {
			if (path.getFirst().equals(f.getName())) {
				if (path.getLength()==1) {
					return new DavFolder(f);
				} else {
					return recursePath(path.getStripFirst(), f);
				}
			}
		}
		for (FileInfo p : FileDAO.getFilesInFolder(parentFolder)) {
			if (path.getFirst().equals(p.getName())) {
				if (path.getLength()==1) {
					return new DavFile(p);
				} else {
					return null;
				}
			}
		}
		return null;
	}
 
}

Download & Install

Step 1

The WebDAV download contains the entire source code (including Eclipse project). The source code is licensed under the terms of the Apache License, Version 2.0. Download this source code and import the project to your Eclipse workspace.

Step 2

Run the MySQL create_script.sql script located in the project folder src-database/scripts in your MySQL database. If you are using another type of DB other than MySQL, please refer to the schema diagram under src-database/model to create the three necessary tables as illustrated.

Step 3

Add a Resource to define a data source for the application to use in your Tomcat context.xml file. Below is an example:
<Resource name="jdbc/MySQLDB" auth="Container" type="javax.sql.DataSource" username="root" password="password" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/test?autoReconnect=true"/>

Step 4

Create, if it doesn’t already exist, a Apache web server instance in Eclipse and publish the application to that server. Then start the application server.

Step 5

Configure your WebDAV client to point to the following URL http://localhost/webdav-example-2/config/ to access the properties through WebDAV.

Concluding Thoughts

Certainly we have all felt the pain of managing application configuration from development environments through to production. This approach attempts to solve some of this pain. The example code provided can be plugged into your application to allow you to quickly move forward on improving the configuration efficiency and accessibility. More valuable, the design and implementation could inspire you to consider other objects your application uses or persists which can be expressed as a file system, giving you unprecedented accessibility.

Use dynamic proxies to create a simple, powerful event bus (Part 1)

In this blog we’ll build on part 1 by adding several important features to the event bus to make it production ready.  Since these features are fairly well contained, you can start with the section that most interests you, download the code, or view the project on GitHub.

• Event Filtering
• Event Topics
• Untyped Listeners
• Exception Handling
• Garbage Collection
• Thread-local Events

Event Filtering

Event filters help reduce noise by allowing listeners to automatically ignore events they would normally receive. This is accomplished by including a new EventFilter object alongside every listener added to the bus.

1
2
3
4
5
6
7

public class EventBus {
 
	...
	public <T extends EventListener> void addListener(Class<T> eventListenerClass,
		EventFilter filter, T listener) { ... }
 
}

The EventFilter class has a single abstract allow(event, listener) method that returns true if the event should be delivered to the listener.

Several filters are already are part of the bus, including EventSourceFilter. This filter only allow events that were produced by one of a set of sources.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class EventSourceFilter implements EventFilter {
 
	private final Object[] source;
 
	public EventSourceFilter(Object ... source) {
		this.source = source;
	}
 
	@Override
	public boolean allow(Event<?> event, Object listener) {
		if (source == null || source.length == 0) {
			return true;
		}
		for (Object s : source) {
			if (event.getEventSource() == s) {
				return true;
			}
		}
		return false;
	}
 
}

In addition to the new EventFilter interface and the addListener update, a few other changes are needed to handle filters:

1. A new EventListenerStub class to hold a listener and filter together.
2. The eventListeners field on EventBus is converted from a Set<? extends EventListener> to a List<EventListenerStub<? extends EventListener>>. We swap Set for List because we can no longer depend on the listener’s object identity to prevent duplicate listeners in the set (now that it’s wrapped in an EventListenerStub).
3. The bus’ deliverEvent() method calls EventFilter.allow()to check if the event should be delivered.

Here’s a quick example of EventSourceFilter in action.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

public class EventSourceFilterExample {
 
	public static void main(String[] args) throws Throwable {
		EventSourceFilterExample eventSource1 = new EventSourceFilterExample();
		EventSourceFilterExample eventSource2 = new EventSourceFilterExample();
		Location store = new Location();
 
		EventBus eventBus = new EventBus();
 
		// listen for events from eventSource1
		eventBus.addListener(WalkListener.class,
				new EventSourceFilter(eventSource1),
				new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("walking from eventSource1...");
			}
		});
 
		// listen for events from eventSource1 or eventSource2
		eventBus.addListener(WalkListener.class,
				new EventSourceFilter(eventSource1, eventSource2),
				new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("walking from eventSource1 or eventSource2...");
			}
		});
 
		// eventSource2 is set as the source for this publisher
		WalkListener publisher = eventBus.getPublisher(eventSource2, WalkListener.class);
 
		publisher.walkTo(store);
		publisher.walkTo(store);
		publisher.walkTo(store);
 
		Thread.sleep(2000L);
		eventBus.shutdown();
		System.out.println("The End.");
	}
 
}

Event Topics

It’s not always ideal for us to filter by the event’s source. Sometimes it’s more convenient to filter by a value known to both publishers and listeners. That’s where topics come in. Topic values can bet passed as an optional parameter while obtaining a publisher from the bus. Every method call made on that publisher will include the topic value. Listeners can watch for specific topics by including a TopicFilter when registering with the bus. Topics can be any java.lang.Object or subclass we like. I recommend enums because they are IDE and refactoring friendly, but a string or any object will do.

Publishers

A few small changes on the publisher side will handle the registration and propagation of topics for us. First, both the Event and EventSourceInvocationHandler classes will track topics. EventSourceInvocationHandler will have it set during construction and pass it on to every event it creates.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

public class EventSourceInvocationHandler<T extends EventListener> implements InvocationHandler {
 
	private final EventBus eventBus;
	private final Object eventSource;
	private final Class<T> eventListenerClass;
	private final Object topic;
 
	public EventSourceInvocationHandler(EventBus eventBus, Object eventSource,
		Class<T> eventListenerClass, Object topic) {
        ...
	}
 
	@Override
	public Object invoke(Object proxy, Method method, Object[] arguments) throws Throwable {
        eventBus.publishEvent(new Event<T>(eventSource, proxy, eventListenerClass,
			topic, method, arguments));
        return null;
	}
 
}

Second, the bus’ getPublisher() method will be overloaded to take in a topic value and set it on the EventSourceInvocationHandler.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public class EventBus {
 
	...
 
	public  T getPublisher(Object eventSource, Class eventListenerClass) {
		return getPublisher(eventSource, eventListenerClass, null);
	}
 
	public  T getPublisher(Object eventSource, Class eventListenerClass, Object topic) {
		EventSourceInvocationHandler handler =
			new EventSourceInvocationHandler(this, eventSource, eventListenerClass, topic);
		return (T) Proxy.newProxyInstance(
				eventListenerClass.getClassLoader(),
				new Class[]{eventListenerClass},
				handler);
	}
 
}

Listeners

The TopicFilter class allows listeners to receive events matching one or more topic values. The implementation uses exact matching, but if that’s too simplistic for your case, it should be easy enough to implement your own hierarchical or pattern matching filter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

public class TopicFilter implements EventFilter {
 
	private final Object[] topic;
 
	public TopicFilter(Object... topic) {
		this.topic = topic;
	}
 
	@Override
	public boolean allow(Event<?> event, Object listener) {
		if (topic == null || topic.length == 0) {
			return true;
		}
		final Object t = event.getTopic();
		for (Object t2 : topic) {
			if (t == t2 || (t != null && t.equals(t2))) {
				return true;
			}
		}
		return false;
	}
 
}

Here’s an example that uses enum topics to publish and filter events.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

public class TopicFilterExample {
 
	public static enum Topic { STROLL, RUSH }
 
	public static void main(String[] args) throws Throwable {
		TopicFilterExample eventSource = new TopicFilterExample();
		Location store = new Location();
 
		EventBus eventBus = new EventBus();
 
		// listen for events under the STROLL topic
		eventBus.addListener(WalkListener.class,
				new TopicFilter(Topic.STROLL),
				new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("walking slowly...out for a stroll");
			}
		});
 
		// listen for events under the RUSH topic
		eventBus.addListener(WalkListener.class,
				new TopicFilter(Topic.RUSH),
				new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("walking quickly...in a rush");
			}
		});
 
		// RUSH is set as the topic for this publisher
		WalkListener publisher = eventBus.
			getPublisher(eventSource, WalkListener.class, Topic.RUSH);
 
		publisher.walkTo(store);
		publisher.walkTo(store);
		publisher.walkTo(store);
 
		Thread.sleep(2000L);
		eventBus.shutdown();
		System.out.println("The End.");
	}
 
}

Untyped Listeners

Some use-cases require that we listen to all events passing through the bus regardless of their type. Audit, monitoring, or even debug requirements might call for such a feature. In these special cases we can register an UntypedEventListener with the bus. These listeners are notified in the form of the Event object after all typed listeners have received their notifications.

EventListenerStub Refactoring

Now that we’re handling both typed and untyped listeners, EventListenerStub will undergo refactoring to reduce code duplication. First, EventListenerStub is divided into three classes. The original EventListenerStub and two inner subclasses: Typed and Untyped. The new subclasses are responsible for providing the delivery logic for their kind of listeners while allowing EventListenerStub to handle filtering and other common behaviour.

Just as before, the Typed subclass invokes the original called method on each listener.

1
2
3
4
5
6
7

class Typed<S extends EventListener> extends EventListenerStub<S> {
        ...
        protected void deliverEventImpl(EventBus eventBus, Event<?> event) throws Throwable {
                S listener = getListener();
                event.getMethod().invoke(listener, event.getArguments());
        }
}

While the Untyped subclass calls the onEvent method on untyped listeners.

1
2
3
4
5
6
7

class Untyped extends EventListenerStub<UntypedEventListener> {
        ...
        protected void deliverEventImpl(EventBus eventBus, Event<?> event) throws Throwable {
                UntypedEventListener listener = getListener();
                listener.onEvent(event);
        }
}

EventBus Refactoring

The event bus gets a few upgrades.

1. The old eventListeners field is renamed to typedListeners to compliment the new untypedListeners field.
2. Both versions of addListener (typed and untyped) take care to add the correct subclass of EventListenerStub to their lists.
3. The bus’ deliverEvent method now delegates to the deliverEvent method on each stub to ensure the correct delivery behaviour.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

public class EventBus {
 
	private final Map<Class<? extends EventListener>, TypedListenerList<?>> typedListeners =
		new HashMap<Class<? extends EventListener>, TypedListenerList<?>>();
 
	private final List<EventListenerStub<UntypedEventListener>> untypedListeners =
		new CopyOnWriteArrayList<EventListenerStub<UntypedEventListener>>();
 
	public <T extends EventListener> void addListener(Class<T> eventListenerClass, EventFilter filter, T listener) {
		TypedListenerList<T> list;
		...
		list.getList().add(new EventListenerStub.Typed<T>(filter, listener));
	}
 
	public void addListener(EventFilter filter, UntypedEventListener listener) {
		untypedListeners.add(new EventListenerStub.Untyped(filter, listener));
	}
 
	protected <T extends EventListener> void deliverEvent(Event<T> event) throws Throwable {
		// Deliver to typed listeners
		TypedListenerList<T> list = getTypedListenerList(event.getEventListenerClass());
		if (list != null) {
			for (EventListenerStub<?> stub : list.getList()) {
				stub.deliverEvent(this, event);
			}
		}
 
		// Deliver to untyped listeners
		for (EventListenerStub<UntypedEventListener> stub : untypedListeners) {
			stub.deliverEvent(this, event);
		}
	}
 
}

Here’s an example of an untyped listener watching all events on the bus.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

public class UntypedEventListenerExample {
 
	public static void main(String[] args) throws Throwable {
		UntypedEventListenerExample eventSource = new UntypedEventListenerExample();
		Location store = new Location();
 
		EventBus eventBus = new EventBus();
 
		eventBus.addListener(null, new UntypedEventListener() {
                  public void onEvent(Event<?> event) {
                    System.out.println("event: " + event.getEventListenerClass().getSimpleName() +
                    "." + event.getMethod().getName() );
                  }
                }); 
 
		WalkListener publisher = eventBus.getPublisher(eventSource, WalkListener.class);
 
		publisher.walkTo(store);
		publisher.walkTo(store);
		publisher.walkTo(store);
 
		Thread.sleep(2000L);
		eventBus.shutdown();
		System.out.println("The End.");
	}
 
}

Exception Handling

So far we haven’t said anything about exceptions. If you’ve looked at the source code from part 1, you’ll see that exceptions were caught, wrapped in RuntimeExceptions, and then rethrown. This saved us from the extra coding to declare checked exceptions, but did nothing to actually handle them. What we need now is an exception handling strategy that:

1. Handles all exceptions regardless of which thread throws them
2. Handles exceptions for both typed and untyped listeners
3. Doesn’t require knowledge of the bus’ internal workings
4. Is decoupled from listeners
5. Is simple to use

Exception Events

We can accomplish all of these requirements by simply leveraging the bus itself. By letting the event bus publish exceptions like any other event, we gain all of its advantages (decoupling, threading, filters, etc.) for the price of a small change.

The new ExceptionListener interface is used for both publishing and observing exceptions. The bus holds a publisher reference which it exposes through its handleException method. Since the bus delegates the actual event delivery to EventListenerStub, that class is also responsible for reporting exceptions to the bus by calling handleException. The handleException method takes care not to introduce infinite loops by not publishing exceptions for events where it was the publisher.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

public class EventBus {
 
	...
 
	private final ExceptionListener exceptionPublisher;
 
	public EventBus() {
		exceptionPublisher = getPublisher(this, ExceptionListener.class);
	}
 
	public void addExceptionListener(EventFilter filter, ExceptionListener listener) {
		addListener(ExceptionListener.class, filter, listener);
	}
 
	protected void handleException(Event<?> event, Object listener, Throwable e) {
		if (e instanceof InvocationTargetException) {
			e = e.getCause();
		}
		if (event.getEventPublisher() != exceptionPublisher) {
			exceptionPublisher.onException(event, e, listener);
		}
	}
 
	...
}

This example prints each exception’s message along with the event class’ name and method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

public class ExceptionListenerExample {
 
	public static void main(String[] args) throws Throwable {
		ExceptionListenerExample eventSource = new ExceptionListenerExample();
		Location store = new Location();
 
		EventBus eventBus = new EventBus();
 
		eventBus.addListener(WalkListener.class, null, new WalkListener() {
			public void walkTo(Location location) {
				throw new RuntimeException("always fails");
			}
		});
 
		eventBus.addExceptionListener(null, new ExceptionListener() { @Override public void onException(Event<?> event, Throwable exception, Object targetListener) { System.out.println("exception in " + event.getEventListenerClass().getSimpleName() + "." + event.getMethod().getName() + ": " + exception.getMessage()); } }); 
 
		WalkListener publisher = eventBus.getPublisher(eventSource, WalkListener.class);
 
		publisher.walkTo(store);
		publisher.walkTo(store);
		publisher.walkTo(store);
 
		Thread.sleep(2000L);
		eventBus.shutdown();
		System.out.println("The End.");
	}
 
}

Garbage Collection

Memory leaks are a real concern when using the observer pattern. Observers that are never unregistered may never get garbage collected and your application’s memory could continue to grow until it eventually fails with an OutOfMemoryError. Memory leaks are arguably even more of a concern when working with event buses because they are responsible for holding on to all observers for all subjects. If a bus lives for the entire run of your app while holding on to every single all observer, we could get that OutOfMemoryError even sooner.

Soft References

The java.lang.ref package is Java’s answer to allowing objects to be garbage collected, even while there are still live references to them. The key is to wrap those objects with one of the classes in this package. In the event bus, we now wrap each listener in a SoftReference. This allows listeners to be automatically garbage collected when memory gets low, but now introduces a level of indirection to our code. We chose to use SoftReference over a WeakReference because they are garbage collected less aggressively by the JVM. Since most listeners tend to be anonymous inner classes, only referenced by the bus, I’d hate to see them disappear while the system is still flush with memory. (For more on Java references, read Ethan Nicholas’ classic blog Understanding Weak References. )

EventListenerStub

The code that manages listeners through soft references can e found in EventListenerStub and its two subclasses — Typed and Untyped. EventListenerStub wraps the listener and ensures the getter method is used for all access. The Typed and Untyped subclasses now perform null checks (in case listeners were garbage collected) before actually delivering events.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

abstract class EventListenerStub<T> {
 
	...
	private final Reference<T> listener;
 
	public EventListenerStub(EventFilter filter, T listener, ReferenceQueue<? super T> referenceQueue) {
		...
		this.listener = new SoftReference<T>(listener, referenceQueue);
	}
 
	protected T getListener() {
		return listener.get();
	}
 
	...
 
	//====================================================================
	//  Typed Implementation
	//====================================================================
 
	final static class Typed<S extends EventListener> extends EventListenerStub<S> {
		...
		protected void deliverEventImpl(EventBus eventBus, Event<?> event) throws Throwable {
			S listener = getListener();
			if (listener != null) { // in case it was garbage collected
				event.getMethod().invoke(listener, event.getArguments());
			}
		}
	}
 
	//====================================================================
	//  Untyped Implementation
	//====================================================================
 
	final static class Untyped extends EventListenerStub<UntypedEventListener> {
		...
		protected void deliverEventImpl(EventBus eventBus, Event<?> event) throws Throwable {
			UntypedEventListener listener = getListener();
			if (listener != null) { // in case it was garbage collected
				listener.onEvent(event);
			}
		}
	}
 
}

Reference Clean-up

You might have noticed the ReferenceQueue parameter in EventListenerStub‘s constructor. Reference queues allow the garbage collector to inform us when the objects in the soft references are actually released. The exact details differ for each kind of reference, but generally the garbage collector will put released references into the queue for us. We simply have to poll the queue periodically to be notified. Using reference queues allow us to be very efficient at detecting garbage collection, it saves us from having to test every listener reference to do a proper clean-up.

The event bus now holds two reference queues for garbage. One queue for typed listeners and the other for untyped. The queues are passed into the EventListenerStub subclasses along with each listener during registration. Finally, each event delivery now finishes with a call to the bus’ cleanupGarbage() method which polls the queues and removes anything found there. Although cleanupGarbage() returns very quickly when queues are empty, you could probably come up with an even better approach than checking every time.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

public class EventBus {
 
	private final ReferenceQueue<? super EventListener> garbageTypedListeners =
		new ReferenceQueue<EventListener>();
 
	private final ReferenceQueue<UntypedEventListener> garbageUntypedListeners =
		new ReferenceQueue<UntypedEventListener>();
 
	...
 
	public <T extends EventListener> void addListener(Class<T> eventListenerClass,
		EventFilter filter, T listener) {
		...
		list.getList().add(new EventListenerStub.Typed<T>(filter, listener, garbageTypedListeners));
	}
 
	protected void removeTypedListenerReference(Reference<?> reference) { ... }
 
	public void addListener(EventFilter filter, UntypedEventListener listener) {
		untypedListeners.add(new EventListenerStub.Untyped(filter, listener, garbageUntypedListeners));
	}
 
	protected void removeUntypedListenerReference(Reference<?> reference) { ... }
 
	protected <T extends EventListener> void deliverEvent(Event<T> event) throws Throwable {
		...
		cleanupGarbage();
	}
 
	protected void cleanupGarbage() {
		Reference<?> reference;
 
		while ((reference = garbageTypedListeners.poll()) != null) {
			removeTypedListenerReference(reference);
		}
 
		while ((reference = garbageUntypedListeners.poll()) != null) {
			removeUntypedListenerReference(reference);
		}
	}
	...
}

Here’s an example that shows soft references surviving a forced garbage collection (System.gc()), but not a true memory exhaustion (allocating 100 GB or RAM). This example was run with the following configuration:

• Sun/Oracle’s JDK 1.6.0.10 running in Eclipse 3.5
• Windows XP Professional, Service Pack 3
• 3 GB or RAM
• Swap file disabled

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

public class GarbageCollectionExample {
 
	public static void main(String[] args) throws Throwable {
		GarbageCollectionExample eventSource = new GarbageCollectionExample();
		Location store = new Location();
 
		EventBus eventBus = new EventBus();
		eventBus.addListener(WalkListener.class, null, new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("walking...");
			}
		});
 
		WalkListener publisher = eventBus.getPublisher(eventSource, WalkListener.class);
 
		publisher.walkTo(store);
 
		// Force GC.  Should remove weak references.
		// Soft references should not be affected
		System.gc();
 
		publisher.walkTo(store);
 
		// Allocate memory until out-of-memory
		// garbage collector remove soft references
		List<byte[]> bytes = new ArrayList<byte[]>(10000);
		try {
			for (int i = 0; i < 10000; i++) {
				bytes.add(new byte[10 * 1024 * 1024]); // allocate 10MB blocks
			}
		} catch (Throwable e) {
			e.printStackTrace();
		}
 
		publisher.walkTo(store);
 
		Thread.sleep(2000L);
		eventBus.shutdown();
		System.out.println("The End.");
	}
 
}

Thread-local Events

In the Untyped Listeners section we saw how to implement a bus wide listener. This gave us access to the raw Event object containing things like the event source, listener interface, and invoked method. Unfortunately, this forced us into choice. Either we listen for typed events and used whatever parameters the listener interface defines or go untyped and have the full Event object. Going untyped means extra filtering coding to select the exact event we’re interested in. Fortunately, we don’t have to make that choice.  We can continue to work with typed listeners and access the full event using a thread-local when needed.

Thread-locals

Thread-locals allow us attach values to the current thread then access those values from any method running on that thread. This saves us having to modify methods to explicitly pass values around. For the event bus, this means linking the Event object to the delivery thread which we can then access anywhere, including inside a typed listener.

The event bus contains all of the changes:

1. A new thread-local field for the event (currentEvent)
2. A getter method for use anywhere (as long as it’s in the delivery thread)
3. Setting and removing the current event during delivery

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

public class EventBus {
 
	private final ThreadLocal<Event<?>> currentEvent = new ThreadLocal<Event<?>>();
 
	...
 
        public Event<?> getCurrentEvent() {
          return currentEvent.get();
        }
 
        protected <T extends EventListener> void deliverEvent(Event<T> event) throws Throwable {
		try {
			currentEvent.set(event);
 
			// Deliver to typed listeners
			TypedListenerList<T> list = getTypedListenerList(event.getEventListenerClass());
			if (list != null) {
				for (EventListenerStub<?> stub : list.getList()) {
					stub.deliverEvent(this, event);
				}
			}
 
			// Deliver to untyped listeners
			for (EventListenerStub<UntypedEventListener> stub : untypedListeners) {
				stub.deliverEvent(this, event);
			}
 
			cleanupGarbage();
		} finally {
			currentEvent.remove();
		}
	}
 
}

This example uses the thread-local’s event to display the name of the invoked method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class ThreadLocalExample {
 
	public static void main(String[] args) throws Throwable {
		ThreadLocalExample eventSource = new ThreadLocalExample();
		Location store = new Location();
 
		final EventBus eventBus = new EventBus();
		eventBus.addListener(WalkListener.class, null, new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("called " + eventBus.getCurrentEvent().getMethod().getName());
			}
		});
 
		WalkListener publisher = eventBus.getPublisher(eventSource, WalkListener.class);
		publisher.walkTo(store);
 
		Thread.sleep(2000L);
		eventBus.shutdown();
		System.out.println("The End.");
	}
 
}

Next Time

That’s a wrap. We’ve covered a lot of ground in this blog. Hopefully, I left you with a few ideas you can use in your own event bus or applications.  Do you have a question or suggestion to improve some of the ideas we’ve discussed?  Leave a comment, I’d like to hear about it.

In part 3 of the Event Bus Series, we’ll discuss implementing the event bus using GWT (Google Web Toolkit) Generators. Stay tuned.

Download

The event bus download contains the entire source code (including Eclipse project). Alternatively, you can view the project on GitHub. The source code is licensed under the terms of the Apache License, Version 2.0.

Example

We will write the logic to create a network drive containing just one file, scratchpad.txt, which can be modified at will from any location where the drive is mounted.
You may want to load the project into your IDE so that you can follow along.

Step 1: Create The Domain Object

public class Scratchpad {
	private static final Scratchpad INSTANCE = new Scratchpad();
 
	private String text = "";
	private Date modifiedDate;
	private final Date createdDate = new Date();
 
	public static Scratchpad get() {
		return INSTANCE;
	}
 
	public String getText() {
		return this.text;
	}
 
	public void setText(String text) {
		this.text = text;
		this.modifiedDate = new Date();
	}
 
	public Date getModifiedDate() {
		return modifiedDate;
	}
 
	public Date getCreatedDate() {
		return createdDate;
	}
}

This is a simple POJO which will allow us to hold some text and attributes which will nicely represent a virtual scratchpad.txt file. Your applications could have something similar which would benefit from being exposed though WebDAV.

Step 2: Create The Equivalent Resource Class As A Composition

public class ScratchpadResource implements PropFindableResource, GetableResource {
 
	private static final String FILENAME = "scratchpad.txt";
 
	public static String getFilename() {
		return FILENAME;
	}
 
	@Override
	public String getUniqueId() {
		return getFilename();
	}
 
	@Override
	public String getName() {
		return getFilename();
	}
 
	@Override
	public Object authenticate(String user, String password) {
		return "anonymous";
	}
 
	@Override
	public boolean authorise(Request request, Method method, Auth auth) {
		return true;
	}
 
	@Override
	public String getRealm() {
		return null;
	}
 
	@Override
	public Date getCreateDate() {
		return Scratchpad.get().getCreatedDate();
	}
 
	@Override
	public Date getModifiedDate() {
		return Scratchpad.get().getModifiedDate();
	}
 
	@Override
	public String checkRedirect(Request request) {
		return null;
	}
 
	@Override
	public Long getMaxAgeSeconds(Auth auth) {
		return null;
	}
 
	@Override
	public String getContentType(String accepts) {
		return "text/plain";
	}
 
	@Override
	public Long getContentLength() {
		return Long.valueOf(Scratchpad.get().getText().length());
	}
 
	@Override
	public void sendContent(OutputStream out, Range range, Map params, String contentType) throws IOException, NotAuthorizedException, BadRequestException {
		out.write(Scratchpad.get().getText().getBytes());
	}
}

In this step, we have created a class with a “has-a” relationship with the original domain object. The key part here is to note which interfaces are implemented. Implementing PropFindableResource allows the file or folder to be searchable. Implementing GetableResource allows you to define how WebDAV will get the content of the virtual file or folder. You should pick the interfaces based on the behavior of the resource. In this example, we want the file to be able to be read, and modified, but never deleted. Subsequently we have implemented only the required interfaces. For more details on these interfaces, please refer to the Milton JavaDoc.
The methods implementations are done in this way so that the virtual scratchpad.txt file behaves like you would expect a text file to behave. Notably sendContent(…) will get the text stored in the POJO and supply it to the OutputStream.

public class RootResource implements PropFindableResource, CollectionResource, PutableResource {
 
	private static final String FOLDERNAME = "root";
 
	@Override
	public String getUniqueId() {
		return FOLDERNAME;
	}
 
	@Override
	public String getName() {
		return FOLDERNAME;
	}
 
	@Override
	public Object authenticate(String user, String password) {
		return "anonymous";
	}
 
	@Override
	public boolean authorise(Request request, Method method, Auth auth) {
		return true;
	}
 
	@Override
	public String getRealm() {
		return null;
	}
 
	@Override
	public Date getCreateDate() {
		return Scratchpad.get().getCreatedDate();
	}
 
	@Override
	public Date getModifiedDate() {
		return Scratchpad.get().getCreatedDate();
	}
 
	@Override
	public String checkRedirect(Request request) {
		return null;
	}
 
	@Override
	public Resource child(String childName) {
		return null;
	}
 
	@Override
	public List getChildren() {
		List resources = new ArrayList();
		resources.add(new ScratchpadResource());
		return resources;
	}
 
	@Override
	public Resource createNew(String newName, InputStream inputStream, Long length, String contentType) throws IOException, ConflictException, NotAuthorizedException, BadRequestException {
		if (ScratchpadResource.getFilename().equals(newName)) {
			StringWriter writer = new StringWriter();
			IOUtils.copy(inputStream, writer, "UTF-8");
			Scratchpad.get().setText(writer.toString());
			return new ScratchpadResource();
		} else {
			throw new BadRequestException(this);
		}
	}
 
}

To keep the file-structure analogy going, we should have a root folder to contain our one file. That’s the purpose of the RootResource class. Once again, key here is to determine which interfaces are implemented based on the behavior that we seek. Implementing PutableResource allows files to be created within this folder using the PUT request.
The methods implementations are done in this way so that the scratchpad.txt file can have it’s contents modified. Any other file that is attempted to be created within the root folder will return an error.

Step 3: Implement The ResourceFactory To Create Your Tree Structure

public class MyResourceFactory implements ResourceFactory {
 
	@Override
	public Resource getResource(String host, String strPath) {
		Path path = Path.path(strPath);
 
		//STRIP PRECEEDING PATH
		path = path.getStripFirst().getStripFirst();
 
		if (path.isRoot()) {
			return new RootResource();
		} else if (path.getFirst().equals(ScratchpadResource.getFilename())) {
			return new ScratchpadResource();
		}
 
		return null;
	}
 
}

Here is where you define how your tree structure will work. What you want to do is think about which resource is being referred to for a given URL. In our simple case, we have just two possible valid URLS: http:///scratchpad/ and http:///scratchpad/scratchpad.txt .
This makes defining our tree structure pretty simple to code up as you can see below. If your tree structure is more complex with several child folders, you may want to consider a recursive strategy.

Step 4: Implement The ResourceFactoryFactory To Allow Milton To Access Your Resource Classes

public class MyResourceFactoryFactory implements ResourceFactoryFactory {
 
	private static AuthenticationService authenticationService;
	private static MyResourceFactory resourceFactory;
 
	@Override
	public ResourceFactory createResourceFactory() {
		return resourceFactory;
	}
 
	@Override
	public WebDavResponseHandler createResponseHandler() {
		return new DefaultWebDavResponseHandler(authenticationService);
	}
 
	@Override
	public void init() {
		if (authenticationService == null) {
			authenticationService = new AuthenticationService();
			resourceFactory = new MyResourceFactory();
		}
	}
 
}

This class exists most importantly to associate the MiltonServlet with the ResourceFactory implementation in the previous step. You can use this class to load some initialization parameters but for our simple example, it was not necessary.

Step 5: Update Your web.xml To Allow Access To Your Milton Servlet And Classes

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>webdav-example</display-name>
...  
  <filter>
    <display-name>WebDAVFilter</display-name>
    <filter-name>WebDAVFilter</filter-name>
    <filter-class>com.northconcepts.webdav.WebDAVFilter</filter-class>
  </filter>
 
  <filter-mapping>
    <filter-name>WebDAVFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
...
</web-app>

Finally, to direct requests appropriately, you will need to update the web.xml so that the MiltonServlet can serve up the content for the desired URLs.

That’s it! You can now point your web browser, WebDAV client, or network drive mount to the server URL that is running this project and you will see the root folder containing the scratchpad.txt file. You can open and edit it as you wish and the content is persisted and automatically shared across any computer that has shared that drive.

Concluding Thoughts

Our example made a single POJO accessible from a cloud. What’s remarkable about WebDAV shows itself when you start to think about the business objects in your application that can be represented in a file format. This would allow direct, real-time access to read and update this data in a way that is both natural and simple to code.

Future WebDAV posts will explore this thought as well as touch on some of the more advanced capabilities WebDAV offers that you find in full-fledged Content Management Systems.

Download

The WebDAV download contains the entire source code (including Eclipse project). The source code is licensed under the terms of the Apache License, Version 2.0.

Event Buses

Event buses act as brokers or clearing houses for notifications. They provide a single point of contact where:

1. Observers can register to be notified of events.
2. Subjects can publish events as they occur.

Event buses are an evolution on the observer pattern. They share many of the same advantages (loose coupling and event broadcasting), while removing several shortcomings:

1. Code duplication. Subjects no longer need to explicitly track their observers. The list of observers, along with the registration and notification logic, can be moved from each subject into the event bus.
2. Decentralized event management. Event registration and notification are no longer spread out over a potentially large number of classes. Centralized management also aids in debugging, eases maintenance, and reduces our overall software complexity.
3. Simplified event wiring. Observers do not need to seek out subjects to register their interest and subjects do not need to notify observers directly when events occur.

Dynamic Proxies

Dynamic proxies are a way to route calls from all methods on one or more Java interfaces to a single function automagically (without programming). This happens while your program is running and doesn’t require recompilation or restart. All it needs is a set of interfaces to automatically implement and a concrete implementation of the java.lang.reflect.InvocationHandler interface to receive the calls.

One Call, Many Receivers

What if we could call a method that instead of being invoked on one object was invoked on several objects automatically? For example, person.walkTo(store) invokes walkTo on a single person object. But what if we could invoke that call on many person objects at once without having to call a fireWalkTo method or create a WalkEvent class (a common way of implementing the observer pattern)? Well, that’s exactly what this event bus does. It lets subjects call methods on the listener interface then invokes those calls on all registered observers.

Quick Example

Before we dive into the details, let’s look at a quick example of how the final product can be used.

First we create a listener interface:

public interface WalkListener extends EventListener {
	void walkTo(Location location);
}

Then we use WalkListener to both observer and publisher events:

public class EventBusExample {

	public static void main(String[] args) {
		EventBusExample eventSource = new EventBusExample();
		Location store = new Location();

		EventBus eventBus = new EventBus();
		eventBus.addListener(WalkListener.class, new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("walking slowly...");
			}
		});
		eventBus.addListener(WalkListener.class, new WalkListener() {
			public void walkTo(Location location) {
				System.out.println("walking quickly...");
			}
		});

		WalkListener publisher = eventBus.getPublisher(eventSource,
			WalkListener.class);

		publisher.walkTo(store);
		publisher.walkTo(store);
		publisher.walkTo(store);

		eventBus.shutdown();
		System.out.println("The End.");

	}

}

Implementation Details

The Event Bus is made up of three collaborating classes: Event, EventSourceInvocationHandler, and EventBus. For most of our use-cases, EventBus is all we’ll need to work with. In some rare cases we may need direct access to the Event object — for example — to log all events flowing through the bus (regardless of type or method). We’ll discuss how to accomplish this in part 2 of this series.

Event Class

The Event class represents a single method invocation from an event source (publisher). It holds the actual invoked java.lang.reflect.Method along with any arguments that were passed into it.

public class Event {

	private final Object eventSource;
	private final Class<? extends EventListener> eventListenerClass;
	private final Method method;
	private final Object[] arguments;

	...
}

EventSourceInvocationHandler Class

EventSourceInvocationHandler is the concrete implementation of InvocationHandler for use with dynamic proxies. Its invoke() method receives all event publisher method calls and posts them to the event bus for delivery.

public class EventSourceInvocationHandler implements InvocationHandler {

	private final EventBus eventBus;
	private final Object eventSource;
	private final Class<? extends EventListener> eventListenerClass;

	public EventSourceInvocationHandler(EventBus eventBus, Object eventSource,
		Class<? extends EventListener> eventListenerClass) {
		this.eventBus = eventBus;
		this.eventSource = eventSource;
		this.eventListenerClass = eventListenerClass;
	}

	public Object invoke(Object proxy, Method method, Object[] arguments)
		throws Throwable {
		eventBus.publishEvent(new Event(eventSource, eventListenerClass,
			method, arguments));
		return null;
	}

}

EventBus Class

EventBus is where all the magic happens. It provides all of the registration, queuing, and delivery services to make the whole thing work. Let’s first look at the bus’ surface area, followed by implementation details of the business methods: getPublisher, addListener, deliverEvent, and publishEvent.

First the basic structure of the bus:

public class EventBus {

	private final Map<Class<? extends EventListener>,
			Set<? extends EventListener>> eventListeners =
		new HashMap<Class<? extends EventListener>,
			Set<? extends EventListener>>();

	private final ExecutorService executorService =
		Executors.newFixedThreadPool(1);

	public EventBus() {
	}

	public <T extends EventListener> void addListener(
		Class<T> eventListenerClass, T listener) {
	}

	public <T extends EventListener> void removeListener(
		Class<T> eventListenerClass, T listener) {
	}

	public void removeListener(EventListener listener) {
	}

	public <T extends EventListener> T getPublisher(Object eventSource,
		Class<T> eventListenerClass) {
		return null;
	}

	protected void publishEvent(Event event) {
	}

	protected void deliverEvent(Event event) {
	}

	public void shutdown() throws InterruptedException {
	}

}

EventBus.getPublisher()

The getPublisher method takes an event source and a listener class then returns an instance of that listener we can call to publish events. The event source can be any object for now. In the next blog we’ll see how we can use it to filter the events observers receive.

public <T extends EventListener> T getPublisher(Object eventSource,
	Class<T> eventListenerClass) {

	EventSourceInvocationHandler handler =
		new EventSourceInvocationHandler(this, eventSource,
		eventListenerClass);

	return (T) Proxy.newProxyInstance(
			eventListenerClass.getClassLoader(),
			new Class[]{eventListenerClass},
			handler);

}

EventBus.addListener()

Observers register for events by calling addListener() with the EventListener interface they are interested in and an object that implements it. CopyOnWriteArraySet is used because it is thread-safe without requiring much synchronization. This means we have the option to notify observers using separate threads without blocking registrations.

public <T extends EventListener> void addListener(Class<T> eventListenerClass,
	T listener) {
	Set<T> listeners;
	synchronized (eventListeners) {
		listeners = (Set<T>) eventListeners.get(eventListenerClass);
		if (listeners == null) {
			listeners = new CopyOnWriteArraySet<T>();
			eventListeners.put(eventListenerClass, listeners);
		}
	}
	listeners.add(listener);
}

EventBus.deliverEvent()

Event delivery is performed by invoking the original method called by the producer on every registered observer.

protected void deliverEvent(Event event) throws Throwable {
	Set<? extends EventListener> listeners;
	synchronized (eventListeners) {
		listeners = eventListeners.get(event.getEventListenerClass());
	}
	if (listeners != null) {
		for (EventListener listener : listeners) {
			event.getMethod().invoke(listener, event.getArguments());
		}
	}
}

EventBus.publishEvent()

Events are queued for delivery by adding a Runnable with the actual delivery task to the executor service. Executors are a great way to benefit from concurrency without the complexity (and subtle bugs) that come with writing multi-threaded code.

	protected void publishEvent(final Event event) {
		executorService.execute(new Runnable(){
			@Override
			public void run() {
				try {
					deliverEvent(event);
				} catch (Throwable e) {
					throw new RuntimeException(e.getMessage(), e);
				}
			}
		});
	}

Next Time

That’s all for now. I hope you’ve found this application of dynamic proxies useful. Please leave a comment if you have any suggestions, questions, or ideas on dynamic proxies or event busses.

In the next part of this series, we’ll focus on several topics (exception handling, garbage collection, etc.) to help round out the bus’ feature set.

Download

The event bus download contains the entire source code (including Eclipse project). The source code is licensed under the terms of the Apache License, Version 2.0.

• added JdbcValueReaderto allow clients to override column reading strategy
• added the JdbcReader.valueReader property

• added the XmlTemplate functionality
• XmlWriter now uses XmlTemplate to describe output patterns

• added batch execution to JdbcWriter (see JdbcWriter.setBatchSize)
• added callback mechanism to track job progress (see JobTemplate.transfer(R reader, W writer, boolean async, JobCallback callback))
• early access to DeMuxReader