Spring liefert in der Core Library zwei Implementationen mit. Den ConcurrentMapCacheManager, der die Daten in einer ConcurrentMap speichert, und den EhCacheCacheManager der im Hintergrund EhCache benutzt. Weiter gibt es noch den NoOpCacheManager. Dieser cacht keine Daten und kann nützlich sein für Tests.

Andere Cache Libraries in das Spring Cache System zu integrieren ist nicht schwer. Eine interessante Cacheimplementation ist in der Google Guava Library enthalten.

Seit Version 10 existiert die Klasse CacheBuilder. Damit lassen sich verschiedenste Arten von Caches erstellen. Der CacheBuilder kann Caches mit einer maximalen Grösse erstellen oder Caches in denen die Einträge nach einer bestimmten Zeit gelöscht werden. Caches können erstellt werden die WeakReferences als Key und/oder Value benutzen. Der Guava Cache speichert, wie der ConcurrentMapCache, die Daten nur lokal im Speicher in einer Virtual Machine ab. Für verteilte und/oder persistente Caches sollte man sich den EhCacheCacheManager genauer ansehen.

Caches lassen sich dank des Builder Patterns sehr einfach erstellen. Hier ein Beispiel eines Caches der maximal 10 Einträge enthalten kann und die Einträge 10 Sekunden nach dem Einfügen wieder löscht.

Cache<Integer,String> cache = CacheBuilder.newBuilder()
         .maximumSize(10)
         .expireAfterWrite(10, TimeUnit.SECONDS)
         .build();

cache.put(1, "one");		
System.out.println(cache.getIfPresent(1));

Werte werden mit put(key, value) eingefügt und mit getIfPresent(key) wieder ausgelesen. Weitere Informationen zum Guava Cache findet man in der Wiki unter http://code.google.com/p/guava-libraries/wiki/CachesExplained.

Um nun den Guava Cache mit dem Spring Cache System zu verheiraten benötigen wir zwei Dinge. Erstens eine Klasse die das Interface org.springframework.cache.Cache implementiert und als Zweites einen CacheManager.

Die Cache Implementation ist ein simpler Wrapper der einen Guava Cache beinhaltet.

public class GuavaCache implements Cache {

	private final String name;
	private final com.google.common.cache.Cache<Object, Optional<Object>> store;

	public GuavaCache(String name, com.google.common.cache.Cache<Object, Optional<Object>> store) {
		this.name = name;
		this.store = store;
	}

	@Override
	public String getName() {
		return this.name;
	}

	@Override
	public com.google.common.cache.Cache<Object, Optional<Object>> getNativeCache() {
		return this.store;
	}

	@Override
	public ValueWrapper get(Object key) {
		Optional<Object> value = this.store.getIfPresent(key);
		return (value != null ? new SimpleValueWrapper(value.orNull()) : null);
	}

	@Override
	public void put(Object key, Object value) {
		this.store.put(key, Optional.fromNullable(value));
	}

	@Override
	public void evict(Object key) {
		this.store.invalidate(key);
	}

	@Override
	public void clear() {
		this.store.invalidateAll();
	}
}

Ein Sonderfall der behandelt werden muss ist der null Wert. Der Guava Cache erlaubt keine Werte die null sind, aber es kann durchaus sein das eine @Cacheable Methode null zurückgibt. Um den null Wert auch speichern zu können, wird der Wert in ein Optional Objekt gewrappt. Optional ist auch Bestandteil der Guava Library. Die Methode Optional.fromNullable(obj) gibt entweder eine Optional Instanz zurück, die das Original Objekt umschliesst, oder wenn der Parameter null ist das Objekt Optional.absent(), eine Optional Instanz die kein Objekt wrappt. Mit der Methode optional.orNull() erhalten wir wieder das Original Objekt oder null.

Als CacheManager benutzen wir in diesem Beispiel die Klasse SimpleCacheManager, welche von Spring mitgeliefert wird. Dieser Manager ist für diesen Zweck ausreichend und managt die Namen der Caches zu den tatsächlichen Implementationen.

@Configuration
@EnableCaching
@ComponentScan(basePackages = { "ch.rasc.caching.guava" })
public class Config {

	@Bean
	public CacheManager cacheManager() {
		SimpleCacheManager cacheManager = new SimpleCacheManager();
		
		Cache<Object, Optional<Object>> oneMinuteCache = CacheBuilder.newBuilder()
				.expireAfterWrite(1, TimeUnit.MINUTES).build();

		Cache<Object, Optional<Object>> maxSizeCache = CacheBuilder.newBuilder()
				.maximumSize(10).build();
		
		cacheManager.setCaches(Arrays.asList(
				new GuavaCache("oneMinuteCache", oneMinuteCache),
				new GuavaCache("maxSizeCache", maxSizeCache)
				));
		
        return cacheManager;
	}
}

Das Beispiel erstellt einen Guava Cache mit einer maximalen Grösse von 10 Einträgen und einen zweiten Cache bei dem die Einträge nach einer Minute wieder gelöscht werden. Diese werden mit den Namen “oneMinuteCache” und “maxSizeCache” im CacheManager eingetragen.

Nun können wir sehr einfach die Methoden mit @Cacheable annotieren und den gewünschten Cache spezifizieren.

@Service
public class Calculator {
	@Cacheable("oneMinuteCache")
	public BigInteger factorialTimedCache(long n) {
		//...
	}

	@Cacheable("maxSizeCache")
	public BigInteger factorialMaxCache(long n) {
	          //...
	}
}

Beachten muss man bei diesen Caches das Einträge per Default nicht in einem Hintergrundjob aus dem Cache gelöscht werden. Das Cleanup passiert beim Schreiben oder Lesen eines Eeintrages.

Weitere Informationen zu diesem Thema findet man in der Guava Wiki:
http://code.google.com/p/guava-libraries/wiki/CachesExplained#Explicit_Removals

Wie in der Wiki beschrieben, wird das Cleanup bei Caches die sehr selten Werte eintragen in den Leseoperationen durchgeführt und kann dadurch das Lesen verlangsamen. Man kann dies vermeiden, indem ein Hintergrundjob gestartet wird der regelmässig die Methode Cache.cleanUp() aufruft.

Hier ein Beispiel eines Jobs der mit Hilfe von ScheduledExecutorService alle 20 Sekunden die Methode cleanUp() von allen Caches aufruft.

@Service
public class CacheCleanup {

	private ScheduledExecutorService scheduler;

	@Autowired
	CacheManager cacheManager;

	@PreDestroy
	public void shutdown() {		
		scheduler.shutdown();
	}

	@PostConstruct
	public void cacheCleanup() {
		scheduler = Executors.newScheduledThreadPool(1);
		scheduler.scheduleWithFixedDelay(new Runnable() {
			@Override
			public void run() {
				for (String cacheName : cacheManager.getCacheNames()) {
					((GuavaCache) cacheManager.getCache(cacheName)).getNativeCache().cleanUp();
				}
			}
		}, 5, 20, TimeUnit.SECONDS);

	}
}

Source Code: https://github.com/ralscha/playground/tree/master/caching/src/main/java/ch/rasc/caching/guava

Spring liefert zwei Implementationen des CacheManagers mit. ConcurrentMapCacheManager und EhCacheCacheManager. Für die folgenden Beispiele werden JavaConfig und ConcurrentMap als Cache verwendet.

@Configuration
@ComponentScan(basePackages = { "ch.rasc.caching.spring" })
@EnableCaching
public class Config {
  @Bean
  public CacheManager cacheManager() {
    return new ConcurrentMapCacheManager("calculator");
  }
}

Als Parameter für den Konstruktor von ConcurrentMapCacheManager werden die Namen der Caches mitgegeben. Es können dann nur diese verwendet werden. Wenn die Klasse mit dem Default Konstruktor ohne Parameter instanziiert wird werden die Caches bei Bedarf erzeugt. Es empfiehlt sich die Cache Namen vorab zu definieren, da Schreibfehler zu Exceptions führen und Fehler so schneller gefunden werden.

Alternativ kann die Config Klasse das Interface CachingConfigurer implementieren.

@Configuration
@ComponentScan(basePackages = { "ch.rasc.caching.spring" })
@EnableCaching
public class Config implements CachingConfigurer {
  @Bean
  @Override
  public CacheManager cacheManager() {
    return new ConcurrentMapCacheManager("calculator", "anotherCache");
  }

  @Override
  public KeyGenerator keyGenerator() {
    return new DefaultKeyGenerator();
  }
}

Caches sind im Grunde nichts anderes als Key-/Value-Stores. Als Wert wird der Rückgabewert der Methode verwendet. Es macht also nur Sinn Methoden cachbar zu machen die etwas zurückgeben. Der Key wird aus den Parametern der Methode gebildet. Die Klasse DefaultKeyGenerator wird von Spring immer dann verwendet wenn kein anderer KeyGenerator spezifiziert wurde.

Nun erzeugen wir ein Service Bean mit einer Methode die cachbar gemacht werden soll.

@Service
public class Calculator {
  @Cacheable("calculator")
  public BigInteger factorial(long n) {
    //...
  }
}

Der Annotation @Cacheable muss der Name des Caches mitgegeben werden. Dies entspricht dem Namen den man beim Instanziieren des CacheManagers verwendet hat. Wenn der Cache nicht existiert wird eine Exception geworfen (ausser man verwendet die dynamische Variante des ConcurrentMapCacheManager). Es ist möglich mehrere Caches anzugeben

@Cacheable(value={"calculator", "anotherCache"})

Per Default werden immer alle Methodenparameter für die Key Generierung verwendet. Man kann dieses Verhalten mit dem Argument key anpassen.

Im folgenden Beispiel wird nur der erste Parameter (n) als Key verwendet. Als Wert für das Argument key muss eine SpEL Expression angegeben werden. Den Namen des Parameters kann nur dann verwendet werden wenn der Code mit Debug Informationen kompiliert wurde. Alternativ kann deshalb der Parameter mit a# oder p# (#=Position des Parameters) spezifiziert werden.

Die folgenden drei Beispiele sind alle gleichwertig:

@Cacheable(value="calculator", key="#n")
public BigInteger factorial(long n, String user) {
  //...
}
@Cacheable(value="calculator", key="#p0")
public BigInteger factorial(long n, String user) {
  //...
}
@Cacheable(value="calculator", key="#a0")
public BigInteger factorial(long n, String user) {
  //...
}

Es ist möglich das Caching nur dann zu benutzen wenn eine bestimmte Bedingung eintritt. Dazu wird mit dem Argument condition eine SpEL Expression angegeben die entweder true oder false zurückgibt. Nur wenn diese Bedingung eintritt (true) wird das Caching benutzt. Im folgenden Beispiel nur dann wenn der Parameter n einen Wert grösser 10 hat.

@Cacheable(value="calculator", condition="#n > 10")
public BigInteger factorial(long n) {
  //...
}

Cache Einträge löschen

Um Cache Einträge wieder zu löschen wird die Annotation @CacheEvict verwendet. Ein Anwendungsfall ist ein Cache für eine Datenbank. Die Abfragemethoden werden mit @Cacheable und die Modify Methoden mit @CacheEvict annotiert, so dass im Cache keine veralteten Werte eingetragen sind.

Beim Aufruf der folgenden Methode wird der Eintrag mit dem Key n im Cache gelöscht. Wenn das nächste Mal eine @Cacheable Methode mit diesem Cache und gleichem Parameter n aufgerufen wird, wird diese wieder ausgeführt. Der Rückgabewert einer @CacheEvict Methode wird für das Cache Handling ignoriert und kann void sein.

@CacheEvict(value="calculator")
public void clearCache(long n) {
}

Es ist möglich, gleich wie bei @Cacheable, den Parameter zu spezifizieren der als Key verwendet werden soll.

@CacheEvict(value = "calculator", key = "#n")
public void clearCache(long n, String user) {
  //nothing here
}

Anstatt nur einen Eintrag zu löschen können mit dem Argument allEntries=true alle Einträge des Caches gelöscht werden. Gleich wie bei @Cacheable ist es möglich mehrere Caches anzugeben die betroffen sind.

@CacheEvict(value = { "calculator", "anotherCache" }, allEntries = true)
public void clearCache() {
  //...
}

Proxy/AspectJ Modus

Per Default verwendet Spring Proxies für das Cachemanagement. Diese werden zur Laufzeit erzeugt und es ist keine spezielle Konfiguration notwendig. Proxies haben aber den Nachteil das nur public Methoden mit @Cacheable annotiert werden können. Man kann zwar auch andere Methoden damit annotieren, dies führt beim Aufruf zu keinem Absturz allerdings wird der Rückgabewert nicht gecacht. Zusätzlich haben Proxies den Nachteil, dass wenn die @Cacheable Method von innerhalb der Klasse aufgerufen wird, das Cachehandling nicht angestossen wird (auch bei public Methoden). Die gleichen Einschränkungen existieren auch bei @Transactional Methoden.

Hier ein Beispiel. Wenn die Methode factorial von ausserhalb des Calculators aufgerufen wird, werden die Rückgabewerte gecacht. Wenn wir nun aber die Methode callFromInside() aufrufen, welche wiederum die Methode factorial ausführt, wird das Caching umgangen und die Methode wird immer ausgeführt.

@Service
public class Calculator {

  public BigInteger callFromInside() {
    return factorial(69);
  }

  @Cacheable("calculator")
  public BigInteger factorial(long n) {
    //...
  }
}

Wenn man nicht-public Methoden cachbar und/oder Methoden von innerhalb der Klasse aufrufen möchte können anstatt Proxies AspectJ verwendet werden. AspectJ verwebt (weave) den Bytecode des Cachehandlings direkt in die Klasse. Das passiert entweder zur Compile- oder zur Load-Time. Hier das Vorgehen um Compile-Time-Weaving zu aktivieren.

Zum einen müssen wir AspectJ im Spring ApplicationContext einschalten. Entweder via JavaConfig @EnableCaching(mode=AdviceMode.ASPECTJ) oder via XML <cache:annotation-driven mode=”aspectj”/>.

Zusätzlich benötigen wir zwei zusätzliche Dependencies für unser Programm.

<dependency>
			<groupId>org.aspectj</groupId>
			<artifactId>aspectjrt</artifactId>
			<version>1.6.12</version>
		</dependency>

		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-aspects</artifactId>
			<version>3.1.1.RELEASE</version>
		</dependency>

Damit Maven den AspectJ Compiler startet integrieren wir das aspectj-maven-plugin Plugin ins pom.xml

<plugin>
				<groupId>org.codehaus.mojo</groupId>
				<artifactId>aspectj-maven-plugin</artifactId>
				<version>1.4</version>
				<configuration>
				    <Xlint>warning</Xlint>
					<complianceLevel>1.7</complianceLevel>
					<source>1.7</source>
				    <target>1.7</target>
					<encoding>UTF-8</encoding>
					<aspectLibraries>
						<aspectLibrary>
							<groupId>org.springframework</groupId>
							<artifactId>spring-aspects</artifactId>							
						</aspectLibrary>						
					</aspectLibraries>
				</configuration>
				<executions>
					<execution>
						<goals>
							<goal>compile</goal>
							<goal>test-compile</goal>
						</goals>
					</execution>
				</executions>
			</plugin>

Wenn man mit Eclipse arbeitet müssen die “AspectJ Capability” eingeschaltet werden. Mit dem neuesten Eclipse und m2e Plugin wird dies automatisch eingeschaltet, wenn das aspectj-maven-plugin Plugin im pom.xml eingetragen wird.

Für die Testprogramme hatte ich das Problem dass der AspectJ Compiler folgenden Fehler anzeigte:
[ERROR] can't determine superclass of missing type org.springframework.transaction.interceptor.TransactionAspectSupport
Dies hat damit zu tun das spring-aspects.jar neben den Cache- auch noch Transaktionsaspekte (für @Transactional) beinhaltet und AspectJ versucht auch diese zu verweben. Man kann nun entweder die benötigten Libraries hinzufügen (spring-tx) oder man konfiguriert das aspectj-maven-plugin Plugin mit <Xlint>warning</Xlint>. Damit erhalten wir zwar einige Warnungen aber der Code kann kompiliert werden.

Diese Einstellung wird leider nicht ins AspectJ Tool von Eclipse übernommen, deshalb musste ich dort noch folgende Einstellung vornehmen um den Code auch via Eclipse kompilieren zu können.

Falls beim Starten des Javaprogramms folgender Fehler auftaucht
Exception in thread "main" java.lang.VerifyError: Expecting a stackmap frame at branch
muss die JVM mit dem Argument -XX:-UseSplitVerifier gestartet werden.

Weitere Informationen findet man in der Spring Dokumentation:
http://static.springsource.org/spring/docs/3.1.x/spring-framework-reference/html/cache.html

Source Code:
https://github.com/ralscha/playground/tree/master/caching/src/main/java/ch/rasc/caching/spring

Haben wir zum Beispiel einen Cluster von Virtual Machines die untereinander Events austauschen möchten dann benötigen wir eine andere Lösung. Für dieses Szenario können wir einen JMS (Java Message Service) einsetzen auf den alle beteiligten Subscriber und Publisher eine Verbindung aufbauen.

Eine alternative Lösung wird im folgenden beschrieben die Hazelcast einsetzt. Diese Lösung bietet nicht die umfangreiche Funktionalität an die ein JMS zur Verfügung stellt, aber für ein einfaches Pub/Sub System zwischen mehreren Virtual Machine kann dieser Ansatz je nach Anforderungen durchaus genügen. Die Hazelcast Lösung hat den Vorteil das wir keinen zentralen Server aufsetzen müssen, da sich die einzelnen Virtual Machines via Multicast finden und kommunizieren. Die einzelnen Knoten müssen sich dazu im gleichen Netz befinden und Multicast muss eingeschaltet sein.

Wie üblich benötigen wir auch hier ein Objekt das als Event verwendet wird. Das Objekt muss Serializable sein damit es von einer Virtual Machine zur anderen gesendet werden kann.

public class ShortMessageEvent implements Serializable {
	private String msg;

	public ShortMessageEvent(String msg) {
		this.msg = msg;
	}

	public String getMsg() {
		return msg;
	}

	public void setMsg(String msg) {
		this.msg = msg;
	}
}

Der Sender benötigt eine Referenz zu einem ITopic um damit das Event zu versenden. Das ITopic erhält man mit einem Aufruf von Hazelcast.getTopic(..)

public void send(String msg) {
	ITopic<ShortMessageEvent> topic = Hazelcast.getTopic ("my_topic");
	topic.publish(new ShortMessageEvent(msg));
}

Der Subscriber muss das Interface MessageListener implementieren. Zusätzlich muss er sich beim Hazelcast Topic registrieren. Im folgenden Beispiel ist der Listener ein Spring Managed Bean und die Registrierung erfolgt in einer @PostConstruct Methode. Wichtig ist das der gleiche Topic Name wie beim Publisher verwendet wird.

public class ShortMessageListener implements MessageListener<ShortMessageEvent> {

	@PostConstruct
	public void register() {
		Hazelcast.<ShortMessageEvent>getTopic("my_topic").addMessageListener(this);
	}

	@Override
	public void onMessage(Message<ShortMessageEvent> message) {
		System.out.println(message.getMessageObject().getMsg());
	}
}

Nun kann der Publisher in einer Virtual Machine (siehe Klasse Client) und der Listener (Server) in einer anderen gestartet werden und man sieht wie die Meldungen versendet werden und der entsprechende Listener aufgerufen wird. Für dieses Beispiel benutzen wir die Default Konfiguration von Hazelcast. Hazelcast kann mit Hilfe der Datei hazelcast.xml, die sich im Klassenpfad befinden muss, detailiert konfiguriert werden.

Alternativ lassen sich Meldungen via das Hazelcast Client API versenden. Dies hat den Vorteil das sich das Programm nicht am Cluster anmelden muss was einige Zeit kosten kann, da beim Aufstarten von Hazelcast die anderen Member des Clusters gesucht werden müssen. Dies kann zum Beispiel sinnvoll sein für ein Batchprogramm das regelmässig Meldung absetzen muss und dann wieder beendet wird. Allerdings muss bei dieser API die IP Adressen der einzelnen Clusterknoten angegeben werden. Sinnvollerweise übergibt man mehrere IP Adresse damit die Meldung trotzdem abgesetzt werden kann auch wenn ein Knoten nicht laufen sollte.

ClientConfig clientConfig = new ClientConfig();
clientConfig.addAddress("localhost");

HazelcastInstance client = HazelcastClient.newHazelcastClient(clientConfig);			
client.getTopic("my_topic").publish(new ShortMessageEvent("message from a simple hazelcast client"));

Source Code: https://github.com/ralscha/playground/tree/master/eventbus/src/main/java/ch/rasc/pubsub/hazelcast

Seit Version 10.0 hat die Google Guava Library auch Support um ein einfaches Publish-Subscribe System aufzubauen. Das folgende Beispiel zeigt eine Möglichkeit wie man dies in einer Spring Applikation einsetzen kann. Die Pub/Sub Klassen der Google Guava Library haben ein paar kleine Vorteile gegenüber einer reinen Spring Lösung die im folgenden beschrieben werden.

Zentrales Element ist die Klasse EventBus. Dies ist der Vermittler der die Messages von einem Publisher entgegennimmt und an interessierte Subscriber weiter leitet. Der EventBus wird sinnvollerweise als Singleton instanziiert und kann sehr einfach mit Spring verwaltet werden.

@Configuration
public class SpringConfig {
	@Bean
	public EventBus eventBus() {
		EventBus eventBus = new EventBus();
		return eventBus;
	}
}

Eine Applikation kann aber auch mehrere EventBus Instanzen besitzen um damit beispielsweise verschiedene Bereiche/Module voneinander abzugrenzen.

Wie mit der Spring-Lösung benötigen wir auch hier Objekte die als Events vom Publisher zum Subscriber gesendet werden. Im Gegensatz zur reinen Spring-Lösung kann der EventBus von Guava jedes beliebige Objekt als Event verarbeiten. Es muss kein Interface implementiert oder eine Superklasse abgeleitet werden.

public class MsgEvent {
	private String message;

	public MsgEvent(String message) {
		this.message = message;
	}

	public String getMessage() {
		return message;
	}
}

Der Publisher benötigt eine Referenz des EventBus damit er Events versenden kann. Mit Aufruf der post Methode wird das Event Objekt versendet.

@Service
public class Publisher {

	private EventBus eventBus;

	@Autowired
	public Publisher(EventBus eventBus) {
		this.eventBus = eventBus;
	}

	public void publishMsgEvent(String message) {
		eventBus.post(new MsgEvent(message));
	}
}

Der Subscriber ist in diesem Beispiel auch ein gewöhnliches Spring Managed Bean. Es muss kein Interface implementiert werden, aber dafür muss für jedes Event das man verarbeiten möchte eine Methode erstellt werden die mit der Annotation @Subscribe gekennzeichnet ist. Die Methode muss public sein und als einzigen Parameter das gewünschte Event Objekt besitzen.

@Service
public class Subscriber {
	@Subscribe
	public void handleMsgEvent(MsgEvent event) {
		System.out.println("MsgEvent: " + event.getMessage());
	}	
}

Ein Subscriber ist nicht auf ein Event beschränkt sondern kann mehrere verschiedene Events verarbeiten in dem für jedes gewünschte Event eine Methode implementiert wird.

@Service
public class Subscriber {

	@Subscribe
	public void handleMsgEvent(MsgEvent event) {
	...
	}

	@Subscribe
	public void handleSpecialMsgEvent(SpecialMsgEvent event) {
	...
	}

	...
}

Als letzten Schritt müssen sich alle Subscriber beim EventBus registrieren. Dies geschieht mit der Methode EventBus.register. Wir könnten die EventBus Instanz in unseren Subscriber injizieren und dann zum Beispiel im Konstruktor oder einer @PostConstruct Methode eventBus.register(this) aufrufen. Bei vielen verschiedenen Subscriber Klassen kann dies umständlich werden oder sogar vergessen werden.

Da in diesem Beispiel die Subscriber als Spring Beans implementiert sind können wir stattdessen einen BeanPostProcessor implementieren der die Registrierung übernimmt. Die Methoden des BeanPostProcessor werden für jedes registrierte Bean des ApplicationContext aufgerufen. In der Methode postProcessAfterInitialization untersucht der Processor ob eine Methode mit der Annotation @Subscribe gekennzeichnet ist. Wenn ja wird das Bean im EventBus registriert.

@Service
public class EventBusSubscriberRegisterar implements BeanPostProcessor {

	private EventBus eventBus;

	@Autowired
	public EventBusSubscriberRegisterar(EventBus eventBus) {
		this.eventBus = eventBus;
	}

	@Override
	public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
		return bean;
	}

	@Override
	public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {

		for (Method method : bean.getClass().getMethods()) {
			if (method.getAnnotation(Subscribe.class) != null) {
				eventBus.register(bean);
				break;
			}
		}

		return bean;
	}
}

Damit ist das Pub/Sub System einsatzbereit und ein Aufruf der Publisher.publishMsgEvent(…) löst den Aufruf des Listeners aus.

Hierarchische Events

Ein Feature des Guava EventBuses ist das die Event Objekte hierarchisch sind. Eine Subscriber Methode erhält nicht nur die Events des spezifizerten Parametertyps sondern auch von allen Subklassen davon. Nehmen wir als Beispiel die folgenden beiden Event Objekte.

public class MsgEvent {
...
}

public class SpecialMsgEvent extends MsgEvent {
...
}

Ein Subscriber kann Messages vom Typ SpecialMsgEvent verarbeiten indem er folgende Methode implementiert. Diese Methode wird nur dann aufgerufen wenn ein Publisher ein SpecialMsgEvent versendet.

@Subscribe
public void handleSpecialMsgEvent(SpecialMsgEvent event) {
  ...
}

Folgende Methode mit MsgEvent als Parameter wird dagegen immer dann aufgerufen wenn ein MsgEvent oder ein SpecialMsgEvent verschickt wird, da SpecialMsgEvent eine Subklasse von MsgEvent ist.

@Subscribe
public void handleMsgEvent(MsgEvent event) {
  ...
}

Es ist daher möglich eine Methode mit Object als Parameter zu implementieren. Diese Methode wird für jedes versendete Event aufgerufen, da jedes Objekt in Java eine Subklasses von Object ist.

@Subscribe
public void handleAllEvents(Object event) {
  ...
}

DeadEvent

Ein nützliches Feature während der Entwicklung ist das DeadEvent. Eine Subscribe Methode mit DeadEvent als Parameter wird immer dann aufgerufen wenn für ein Event keine eigene Subscribe Methode implementiert wurde.

@Subscribe
public void handleDeadEvents(DeadEvent deadEvent) {
	System.out.print("Event without a subscriber: ");
	System.out.println(deadEvent.getEvent());
}

Damit findet man recht einfach heraus ob unnütze Events versendet werden oder ob eine Subscribe Methode vergessen wurde zu implementieren.

Asynchrones Eventhandling

Gleich wie bei der reinen Spring-Lösung ruft der EventBus die Subscribe Methoden im gleichen Thread auf wie der Aufruf der eventBus.post Methode. Auch hier kann ein Subscriber den Ablauf blockieren indem umfangreiche Berechnungen gestartet werden. Um das zu verhindern benutzt man anstatt EventBus die Klasse AsyncEventBus. Diese Klasse ruft die Subscribe Methoden in eigenen Threads auf. Dem AsyncEventBus Konstruktor muss ein Executor übergeben werden. Im folgenden ein Beispiel mit einem FixedThreadPool Executor mit 10 Threads. Damit ist es dem EventBus möglich 10 Listeners gleichzeitig in unterschiedlichen Threads aufzurufen.

@Bean
public EventBus eventBus() {
	AsyncEventBus asyncEventBus = new AsyncEventBus(Executors.newFixedThreadPool(10));
	return asyncEventBus;
}

Thread-Safe Handlers

Ein weiteres Feature ist die Möglichkeit Event Handler Methoden als Thread-Safe zu kennzeichen.

@Subscribe
@AllowConcurrentEvents	
public void handleMsgEvent(MsgEvent event) {
	...
}

Ist die Methode nur mit @Subscribe gekennzeichnet dann wird sie vom EventBus mit einem synchronized Block umschlossen und kann dadurch nicht gleichzeitig mehrfach ausgeführt werden. Die Annotation @AllowConcurrentEvents entfernt diesen synchronized Block und ermöglicht es mehreren Threads die Handler Methode gleichzeitig aufzurufen und auszuführen.

Sourcecode dieser Beispiel: https://github.com/ralscha/playground/tree/master/eventbus/src/main/java/ch/rasc/pubsub/guava

Ein klassisches Design Pattern ist das Observer Pattern. Das zu überwachende Objekt (Observable) führt eine Liste von Überwachobjekten (Observer), die beim Auftreten eines Ereignisses informiert werden möchten. Das Observable Objekt ist dann zuständig das die Observer aufgerufen werden.

Beim Publish-Subscribe Pattern enkuppelt man den Sender (Publisher) und den Empfänger (Subscriber) voneinander. Der Sender sendet die Nachricht nicht direkt an den Empfänger sondern an einen Vermittler. Empfänger bekunden ihr Interesse in dem sie beim Vermittler bestimmte Nachrichten abonnieren. Der Vermittler ist dann zuständig das die Nachrichten zu den interessierten Empfängern gelangt. Empfänger und Sender kennen sich in diesem Pattern nicht mehr. Es kann daher vorkommen das niemand ein bestimmtes Event sendet auf das der Empfänger wartet und umgekehrt kann ein Sender Events absetzen die niemanden interessieren.

Ein klassischer Publish/Subscriber Vermittler im Java Umfeld ist Java Message Service (JMS). Dies ist ein Service der entweder eigenständig oder als Bestandteil eines JEE Servers läuft. Verteilte Systeme melden sich an diesem Server Prozess an und können Nachrichten absetzen oder sich als Subscriber anmelden.

Benötigt man nur ein einfaches Eventsystem innerhalb einer Spring Applikation und einer Virtual Machine, dann kann man dies mit den Bordmitteln umsetzen.

Als erstes erstellen wir das Event, das vom Empfänger zum Sender gesendet wird. Die Klasse muss eine Subklasse von org.springframework.context.ApplicationEvent sein.

import org.springframework.context.ApplicationEvent;
public class AppEvent extends ApplicationEvent {
	private String message;

	public AppEvent(Object source, String message) {
		super(source);
		this.message = message;
	}

	public String getMessage() {
		return message;
	}
}

Der Publisher ist ein Spring Managed Bean und benötigt eine Referenz des ApplicationEventPublisher. Mit Hilfe dieser Klasse werden die Events versendet. In diesem Beispiel wird der Publisher via Konstruktor injiziert. In Spring implementiert der ApplicationContext das ApplicationEventPublisher Interface. Die Instanz die in diesem Beispiel injiziert wird ist also ein AnnotationConfigApplicationContext.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Service;

@Service
public class EventPublisher {
	private ApplicationEventPublisher publisher;

	@Autowired
	public EventPublisher(ApplicationEventPublisher publisher) {
		this.publisher = publisher;
	}

	public void publishEvent(String message) {
		publisher.publishEvent(new AppEvent(this, message));
	}
}

Mit der publishEvent Method können Events versendet werden. Als Parameter wird das Event übergeben (Zeile 15).

Der Listener ist auch ein Spring Managed Bean und muss das Interface ApplicationListener implementieren. Dazu muss die Methode onApplicationEvent(AppEvent event) ausprogrammiert werden.

import org.springframework.context.ApplicationListener;
import org.springframework.stereotype.Service;

@Service
public class EventListener implements ApplicationListener<AppEvent> {
	@Override
	public void onApplicationEvent(AppEvent event) {
		System.out.println(new Date() + ": " + event.getMessage());
	}
}

Der Listener muss nicht speziell registriert werden. Es genügt wenn er ein Spring Managed Bean ist. Die Registrierung erfolgt automatisch beim Aufstarten des ApplicationContext.

Wir können nun mit einem Testprogramm die Spring Umgebung starten und das Event versenden und der Listener wird aufgerufen.

public static void main(String[] args) {
	final AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext("ch.rasc.pubsub.spring");
	ctx.getBean(EventPublisher.class).publishEvent("hello world");
}

Ein mögliches Problem ist das per Default alle Listener im gleichen Thread wie der Aufruf der publishEvent Methode des Publisher aufgerufen werden. Dies birgt die Gefahr dass ein Listener den ganzen Ablauf blockieren kann indem er eine umfangreiche Berechnung in der onApplicationEvent Methode startet. Man kann dies Verhindern indem die Listeners in eigenen Threads aufgerufen werden. Dazu muss der SimpleApplicationEventMulticaster, der zuständig für das Ausführen der Listener Methoden ist, mit einem Executor konfiguriert werden. Hier ein Beispiel mit Java Config und einem Executor mit einem Thread Pool von 10 Threads.

@Bean
public ApplicationEventMulticaster applicationEventMulticaster() {
	SimpleApplicationEventMulticaster multicaster = new SimpleApplicationEventMulticaster();
	multicaster.setTaskExecutor(Executors.newFixedThreadPool(10));
	return multicaster;
}

Sourcecode der Beispiele: https://github.com/ralscha/playground/tree/master/eventbus/src/main/java/ch/rasc/pubsub/spring

Eine interessante Neuerung ist die Klasse SXSSFWorkbook. Dies ist eine Streaming Variante der bestehenden XSSFWorkbook Klasse um Excel im Office Open XML Workbook (.xlsx) Format zu erstellen.

Das Problem ist das wenn sehr grosse Excel generiert werden benötigt das XSSFWorkbook sehr viel RAM, da das ganze Workbook im Speicher abgebildet werden muss. Mit SXSSFWorkbook werden immer nur eine konfigurierte Anzahl Rows im Speicher abgelegt und die übrigen Rows in temporäre Dateien zwischengespeichert.

Im folgenden ein Beispiel das ein Excel mit 10’000 Rows zu je 10 Spalten erzeugt. Mit XSSF liegt der Speicherverbrauch bei ca. 122 MB.

Workbook wb = new XSSFWorkbook();
Sheet sh = wb.createSheet();
for (int rownum = 0; rownum < 10000; rownum++) {
	Row row = sh.createRow(rownum);
	for (int cellnum = 0; cellnum < 10; cellnum++) {
		Cell cell = row.createCell(cellnum);
		String address = new CellReference(cell).formatAsString();
		cell.setCellValue(address);
	}

}		
Runtime rt = Runtime.getRuntime();
rt.gc();
System.out.println("Used memory: " + ((rt.totalMemory()-rt.freeMemory())/1024));
File f = new File("xssf.xlsx");
FileOutputStream out = new FileOutputStream(f);
wb.write(out);
out.close();

Um SXSSF zu verwenden muss nur die erste Zeile geändert werden. Der Speicherverbrauch mit SXSSFWorkbook liegt bei ca. 4 MB

Workbook wb = new SXSSFWorkbook(100)

Dem Constructor übergibt man die Grösse des “Row-Window”. Wenn nichts übergeben wird ist der Defaultwert 100 Rows. SXSSF hält in diesem Beispiel immer 100 Rows im Speicher. Sobald die 101. Row erstellt wird, wird die erste Row “geflusht” und kann nicht mehr angesprochen werden. Sobald die 102. Zeile erstellt wird, ist auch die 2 Row nicht mehr ansprechbar usw. Das “Window” bewegt sich also ständig mit und hält die letzten 100 Rows im Speicher.

POI schreibt die “geflushten” Rows in temporäre Dateien. Diese Dateien können unter Umständen sehr gross werden. POI ermöglicht deshalb diese Dateien zu komprimieren. Dazu muss das compressTempFiles Flag auf true gesetzt werden:

((SXSSFWorkbook)wb).setCompressTempFiles(true);

Da mit SXSSF nicht mehr alle Rows im Speicher vorhanden sind gibt es einige Einschränkungen. Löschen von Sheets/Rows/Cells, Rows verschieben und Clonen von Sheets ist nicht möglich. Diese Tabelle listet die Unterschiede und Möglichkeiten der verschiedenen POI Excel Apis auf.

Weitere Infos zu SXSSF findet man auch im Apache POI HOWTO

Ein Aufruf des Konstruktors ohne Argumente liefert ein Objekt mit dem aktuellen Datum und der aktuellen Zeit zurück.

var now = new Date();
var now = Date.now(); //In neueren Browsern

Ein spezifisches Datum lässt sich mit der Übergabe von Argumenten erstellen. Date kann Strings im Format RFC2822 verarbeiten. Neuere Browser unterstützen auch einen Teil des ISO 8601 Standards. Oder man übergibt die Anzahl Millisekunden seit Mitternacht 1.1.1970 UTC. Als dritte Möglichkeit übergibt man Jahr, Monat, Tag und optional Stunden, Minuten, Sekunden, Millisekunden.

new Date(1331121652499); //7. März 2012 13:00:52 GMT+1
new Date("2012-03-07T07:04:12"); //7. März 2012 08:04:12 GMT+1
new Date(2012, 2, 7); //7. März 2012
new Date(2012, 2, 7, 13, 0, 0, 0); //7. März 2012 13:00:00

Beim Monat muss darauf geachtet werden das dieser 0 basiert ist (0 = Januar, 11 = Dezember). Nicht vergessen sollte man new anzugeben. Ohne new erhält man anstatt einem Date einen String zurück, der das aktuelle Datum und Zeit beinhaltet.

Date()    //"Sun Mar 11 2012 11:48:27 GMT+0100 (W. Europe Standard Time)"

Das Date Objekt liefert Funktionen mit um Teile des Datums und der Zeit zu lesen und zu verändern. Zum Beispiel liest folgender Code das aktuelle Jahr.

var now = new Date();
var year = now.getFullYear(); //2012

Mit setFullYear(year) wird das Datum auf ein bestimmtes Jahr gesetzt.

var twoYearsAgo = new Date();
twoYearsAgo.setFullYear(2010);

Eine Auflistung der Date Funktionen findet man auf dem Mozilla Developer Network.

Mit den get/set Funktionen lassen sich auch einfache Berechnungen durchführen. Folgender Code erstellt ein Date Objekt das 3 Tage in der Zukunft liegt.

var d = new Date();
d.setDate(d.getDate()+3);

Differenzen lassen sich mit der Funktion getTime berechnen. Diese Funktion liefert die Anzahl Millisekunden seit dem 1.1.1970 zurück.

var d1 = new Date(2012, 0, 1);
var d2 = new Date(2012, 11, 31);
var diffInMillis = d2.getTime()-d1.getTime()

Ein Schwachpunkt des nativen Date Objektes ist Parsen und Formatieren von Datum und Zeit. Date kennt zwar die parse Funktion aber der String muss entweder als RFC2822 oder ISO 8601 (Subset) übergeben werden. Auch beim Konvertieren in einen String kennt Date einige Funktionen (z.B. toISOString, toLocaleString). Aber wenn man sein eigenes Datumsformat ausgeben will muss dies programmiert werden.

Da Berechnungen und Parsen/Formatieren vom nativen Date Objekt nicht genügend unterstützt werden, gibt es einige Libraries die hier in die Lücke springen und die Behandlung von Datum und Zeit versuchen zu vereinfachen.

Wir schauen uns im folgenden die Libraries XDate, Moment.js und Sugar genauer an.

XDate

XDate ist komprimiert (gzip) 2.9 kB gross und hat keine Abhängigkeit zu anderen Libraries. Das zentrale Objekt in XDate ist XDate. Ein aktuelles Datum mit aktueller Zeit lässt sich, wie das Date Objekt, mit new erstellen.

var now = new XDate();

XDate unterstützt alle Konstruktor Aufrufe die vom Date bekannt sind. Zusätzlich kann ein Date Objekt als Argument dem Konstruktor übergeben werden.

var date = new Date(2010, 0, 1);
var xdate = new XDate(date);

Umgekehrt lässt sich mit toDate aus dem XDate das Date Objekt extrahieren.

var mydate = xdate().toDate();

XDate kennt die vom Date Objekt bekannten get/set Funktionen. Interessant sind die zusätzlichen Funktionen mit denen sich Berechnungen durchführen lassen. Folgendes Beispiel berechnet die Differenz in Tagen bis zu Weihnachen.

var now = new XDate()
var xmas = new XDate();
xmas.setDate(25);
xmas.setMonth(11);
var diffInDays = now.diffDays(xmas);

Für jede Einheit (Year, Month, Week, …) gibt es eine entsprechende diffEinheit Funktion (diffYears, diffMonths, diffWeeks)

Einheiten addieren und subtrahieren lassen sich mit der entsprechenden addEinheit Funktion

var now = new XDate()
now.addDays(3);

var now = new XDate()
now.addDays(-3);

Beim Parsen unterstützt XDate nur Strings im Format ISO8601 und IETF.

new XDate("2011-09-05");
new XDate("2011-09-05T12:30:00Z");

Beim Formattieren bietet XDate mit den Funktionen toString und toUTCString mehr Möglichkeiten als Date. Mann kann diesen Funktionen einen Formatstring mitgeben der das Outputformat beschreibt.

var s = new XDate(2012, 6, 3).toString("dd.MM.yyyy"); //03.07.2012
var s = new XDate(2012, 6, 3).toString("d. MMMM yyyy"); //3. July 2012
var s = new XDate(2012, 6, 3).toString("d. MMM yyyy");

Eine Beschreibung der unterstützten Tokens findet man hier: http://arshaw.com/xdate/#Formatting

Localization wird auch unterstützt. Allerdings müssen die benötigten Strings für Monatsname und Wochentagname selber angegeben werden. Hier ein Beispiel für Französisch: https://gist.github.com/1221376

Moment.js

Diese Library ist minified und komprimiert 3.3 kB gross und hat, wie XDate, keine Abhängigkeit zu anderen Libraries. Moment.js liefert verschiedene Sprachen mit die allerdings nicht im Core Javascript enthalten sind sondern bei Bedarf zusätzlich geladen werden müssen.

Das zentrale Objekt in Moment.js ist moment. Folgender Code erzeugt ein Objekt mit dem aktuellen Datum und Zeit.

var now = moment();

Der Funktion moment können auch ein bestehendes Date Objekt oder die Anzahl Millisekunden übergeben werden um damit ein bestimmtes Datum zu erzeugen.

var d = moment(new Date(2020, 3, 7));
var d = moment(1318781876406);

Eine weitere Möglichkeit ist ein Array mit Parametern zu übergeben. Die Reihenfolge der Zahlen im Array entspricht dem Konstruktor Aufruf beim Date Objekt. Wenn Bestandteile wegelassen werden wird immer der kleinste Wert angenommen.

var d = moment([2012]); // 1 Januar 2012

var d = moment([2012, 2]); // 1 März 2012

var d = moment([2012, 6, 10]); // 10 Juli 2012

Mehr Möglichkeiten als Date und XDate bietet Moment.js beim Parsen von Strings. Hier kann ein Formatstring mitgegeben werden der angibt in welchem Format der String aufgebaut ist.

var d= moment("25.12.2012", "DD.MM.YYYY");

Die Beschreibung der unterstützen Tokens findet man in der Dokumentation: http://momentjs.com/docs/#/parsing/date

Formatieren lässt sich ein Datum mit der format Funktion. Diese Funktion unterstützt die gleichen Tokens wie das Parsen.

d.format("YYYY-MM-DD"); //2012-12-25

Eine Möglichkeit um die Differenz zwischen zwei Daten auszugeben bietet from an. Damit lassen sich Strings wie “a day ago” oder “in 5 days” erzeugen.

var a = moment([2012, 3, 9]);
var b = moment([2012, 3, 20]);

a.from(b); //"11 days ago"
b.from(a); //"in 11 days"
b.from([2012, 3, 21]);  //"a day ago"     

var a = moment([2012, 0, 1, 13, 0, 0]);
var b = moment([2012, 0, 1, 13, 5, 0]);
a.from(b); //"5 minutes ago"
b.from(a); //"in 5 minutes"

Moment.js liefert auch Funktionen mit um einzelne Bestandteile eines Datums zu lesen und zu ändern. Im Gegensatz zu Date haben diese Funktionen kein set/get Prefix.

var day = moment("25.12.2012", "DD.MM.YYYY");
day.date(); // 25

day.date(26);
day.format("DD.MM.YYYY"); //26.12.2012

Diese Funktionen lassen sich auch miteinander verketten.

moment().date(23).hours(0).minutes(0).seconds(0).milliseconds(0);

Um die Zeit auf 00:00:00.000 zu setzen gibt es die Funktion sod (start of day) und eod (end of day) um die Zeit auf 23:59:59.999 zu setzen.

Zusätzlich kann mit day der Wochentag gesetzt werden. Dabei ist 0 = Sonntag und 6 = Samstag. Mit der Subtraktion oder Addition von 7 lässt sich der Wochentag von letzter oder nächster Woche setzen.

var d = moment("07.03.2012", "DD.MM.YYYY");
d.day(5); //Freitag 09.03.2012

d.day(5 + 7); //Freitag 16.03.2012

d.day(5 + 7 + 7); //Freitag 30.03.2012

var d = moment("07.03.2012", "DD.MM.YYYY");
d.day(5 - 7); //Freitag 02.03.2012

Die Funktion diff berechnet Differenzen zwischen zwei Daten. Dabei kann spezifiziert werden in welcher Einheit das Ergebnis zurückgegeben werden soll.

var a = moment([2012, 0, 1]);
var b = moment([2012, 5, 23]);
b.diff(a); //Millisekunden: 15033600000

b.diff(a, 'days'); //Tage: 174

b.diff(a, 'months'); //Monate: 6
b.diff(a, 'months', true); //Monate: 5.7333

Additionen und Subtraktionen lassen sich mit add und subtract durchführen.

var a = moment([2012, 0, 1]);
a.add('days', 10); //11.01.2012
a.subtract('months', 1); //11.12.2011

Eine weitere nützliche Funktion von Moment.js ist isLeapYear die true oder false zurückliefert.

moment([2012]).isLeapYear(); //true
moment([2011]).isLeapYear(); //false

Sugar

Sugar ist keine reine Datumslibrary sondern erweitert alle nativen Javascript Objekte (Array, String, Number, …) um weitere Funktionen. Die Library ist deshalb einiges grösser (17kB gzipped). Sugar liefert aber eine Version aus (sugar-x.x.x-dates-only.min.js) die nur die Datumsfunktionen beinhaltet.

Im Gegensatz zu XDate und Moment.js gibt es hier kein neues Objekt sondern die zusätzlichen Funktion werden im Prototype des entsprechenden Objektes angefügt und stehen dann überall zur Verfügung.

Um ein Datumsobjekt zu erstellen führt Sugar die Funktion create ein.

Date.create(2012, 1);  //1. Februar 2012
Date.create(2012, 1, 13); //13. Februar 2012
Date.create(2012, 1, 13, 10, 45); //13. Februar 2012 10:45 Uhr

Zusätzlich erlaubt es create auch Daten aus Strings zu parsen.

Date.create("2012-02"); //1. Feburar 2012
Date.create("2012-02-13"); //13. February 2012
Date.create("02.13.2012"); //13. February 2012
Date.create("02/13/2012"); //13. February 2012
Date.create("2012-02-13 10:45:00"); //13. Februar 2012 10:45 Uhr
Date.create("February 2012"); //1. Februar 2012

Sugar kann auch spezielle String wie “today” oder “the 13th of next month” verarbeiten. Eine Liste von möglichen Werten findet man in der Dokumentation.

Date.create("today"); //11. März 2012
Date.create("the 13th of next month"); //13. April 2012
Date.create("this week friday"); //16. März 2012
Date.create("last monday"); //5. März 2012
Date.create("10 minutes ago");

Mit der zusätzlichen Angabe einer Sprache werden auch andere Sprachen und Formate verstanden.

Date.create("13.2.2012", "de"); //13. Februar 2012
Date.create("heute", "de"); //11. März 2012
Date.create("aujourd'hui", "fr"); //11. März 2012

Mit set können beliebige Teile des Datums und der Zeit verändert werden.

Date.create().set({day: 21}); //21. März 2012
Date.create().set({day: 21, month: 1}); //21. Februar 2012
Date.create().set({day: 21, month: 1, year: 2015}); //21. Februar 2015

beginningOfUnit setzt das Datum an den Beginn der entsprechenden Einheit. Mit dem Gegenstück endOfUnit setzt man das Datum an das Ende der entsprechenden Einheit.

Date.create().beginningOfWeek(); //11. März 2012
Date.create().beginningOfMonth(); //1. März 2012
Date.create().beginningOfYear(); //1. Januar 2012
Date.create().endOfYear(); //31. Dezember 2012
Date.create().endOfMonth(); //31. März 2012
Date.create().endOfWeek(); //17. März 2012

Für die Datumsarithmetik steht die Funktionen addUnits zur Verfügung. Zusätzlich kann mit rewind und advance das Datum um bestimmte Werte “vorgespult” oder “zurückgespult” werden.

Date.create().addDays(3); //14. März 2012
Date.create().addDays(-3); //8. März 2012
Date.create().addMonths(1); //11. April 2012
Date.create().addMonths(-1); //11. Februar 2012

Date.create().advance({days: 3, months: 1}); //14. April 2012
Date.create().rewind({days: 3, months: 1}); //8. Februar 2012

Sugar bietet umfangreiche Funktionen an um Daten zu vergleichen. Es ist möglich zwei Daten miteinander zu vergleichen und zu prüfen ob eins davon zeitlich vor dem anderen liegt. isBetween erlaubt es zu prüfen ob ein Datum zwischen zwei Daten liegt. isFuture und isPast ermöglichen eine Prüfung ob ein Datum in der Zukunft oder in der Vergangenheit liegt. Mit is kann geprüft werden ob das Datum auf einem bestimmten Tag, Monat, Jahr liegt. isWeekend und isWeekday prüfen das Datum darauf ob es auf einem Samstag-Sonntag oder Montag-Freitag liegt.

var a = Date.create(2012, 0); //1. Januar 2012
var b = Date.create("last day of april"); //30. April 2012
var q = Date.create("2012-03-13"); //13. März 2012

a.isBefore(q); //true
b.isAfter(q); //true
q.isBetween(a,b); //true
q.isBetween("January", "July"); //true
q.isPast(); //false
q.isFuture(); //true
q.isLeapYear(); //true
q.isWeekend(); //false
q.isWeekday(); //true
q.isThisMonth(); //true
q.isToday(); //false
q.is("2012"); //true
q.isAfter("April"); //false
q.is("March"); //true

Differenzen zwischen zwei Daten lassen sich mit unitsSince und unitsUntil berechnen.

var a = Date.create(2012, 7);
var b = Date.create(2012, 8, 23);
   a.daysUntil(b); //53
a.daysSince(b); //-53
a.monthsUntil(b); //2
a.minutesUntil(b); //76320

Mit der Funktion format kann ein Datum auf unterschiedlichste Arten in einen String umgewandelt werden. Dazu übergibt man der Funktionen einen String der das Format beschreibt. Die einzelnen Tokens werden mit geschweiften Klammern {..} umschlossen. Zusätzlich existieren Konstanten, wie Date.ISO8601_DATETIME, die ein standardisiertes Format beschreiben und der format Funktion übergeben werden können.

Date.create().format(); //"March 11, 2012"
Date.create().format('{yyyy}-{MM}-{dd}'); //"2012-03-11"
Date.create().format('{yyyy}-{MM}-{dd} {hh}:{mm}:{ss}'); //"2012-03-11 10:45:33"
Date.create().format('Datum: {dd}. {Month} {yyyy} Zeit: {HH}:{mm}:{ss}', 'de'); //"Datum: 11. März 2012 Zeit: 10:46:44"

Date.create().format(Date.ISO8601_DATETIME); //"2012-03-11T10:47:18.050+01:00"
Date.create().format(Date.RFC1036); //"Sunday, 11-Mar-12 10:47:30 +0100"
Date.create().format(Date.RFC1123, "de"); //"Son, 11 Mär 2012 10:47:43 +0100"

Sugar kennt, wie Moment.js, Funktionen um Strings wie “4 days ago” und “10 minutes from now” zu erzeugen.

Date.create().addMinutes(-10).relative(); //"10 minutes ago"
Date.create().addMinutes(10).relative(); //"10 minutes from now"
Date.create().addMinutes(-10).relative('de'); //"vor 10 Minuten"
Date.create().addMinutes(10).relative('de'); //"in 10 Minuten"
Date.create(2012, 0).relative(); //"2 months ago"

Sugar erweiter nicht nur das Date Objekt, sondern auch das Number Objekt um Datumsfunktionen, wie zum Beispiel unitBefore und unitAfter. Oder die unit Funktionen um eine Einheit in Millisekunden umzurechnen.

(2).hours(); //7200000
(2).milliseconds(); //2
(2).days(); //172800000
(2).months(); //5259600000
(2).daysBefore(Date.create(2012, 0, 5)); //3. Januar 2012
(2).monthsAfter(Date.create("September 2012")); //1. November 2012

Fazit

Date bietet nur minimale Funktionen um mit Daten und Zeiten zu arbeiten. XDate ist vom Funktionsumfang gesehen die kleinste der drei hier vorgestellten Libraries. Wenn in einem Projekt Datumsformatierungen vorgenommen werden, Datumsarithmetik oder Differenzen berechnet werden müssen ist XDate aber eine gute Wahl, die mit einem Overhead von 2.9 kB nicht gross ins Gewicht fällt. Moment.js kennt ein paar Tricks mehr, wie das Parsen von Daten und die relativen Daten (10 minutes ago), und ist mit 3.3 kB nicht viel grösser als XDate.
Sugar ist dann eine gute Wahl wenn man nicht nur die Date Funktionen sondern auch die Erweiterungen der anderen nativen Objekte (String, Number,Array, Objekt, Function, RegExp) benutzen möchte. Alternativ kann aber auch das Sugar Javscript File eingebunden werden das nur die Datumsfunktionen beinhaltet.

Es braucht aber nicht immer eine zusätzliche Datum/Zeit Library. Oft genügt das native Date Objekt in anderen Fällen können die Datumsberechnungen auf dem Server durchgeführt werden und der Client muss die Resultate dann nur anzeigen. Wichtig ist das man die Grösse der Javascript Files im Auge behält. Dies ist dann wichtig wenn Webapplikationen für mobile Geräte entwickelt werden.

Das folgende Beispiel zeigt wie in einer bestehenden Applikation die Icons durch CSS Sprites, mit Hilfe von SmartSprites, ersetzt wurden.

Die Applikation verwendet viele kleine Icons für Buttons. Im CSS finden wir folgenden Code:

.icon-add {
	background-image: url(../images/add.png) !important;  
}

.icon-delete {
	background-image: url(../images/eraser.png) !important;
}

.icon-logging {
	background-image: url(../images/data_scroll.png) !important; 
}

Um SmartSprites anzuweisen diese vielen kleinen Bilder in ein Bild zusammenzufügen, müssen spezielle Kommentare eingefügt werden. Das abgeänderte CSS File sieht danach folgendermassen aus:

/** sprite: sprites; sprite-image: url('../images/sprites.png'); sprite-layout: vertical */

.icon-add {
	background-image: url(../images/add.png) !important;  /** sprite-ref: sprites; */
}

.icon-delete {
	background-image: url(../images/eraser.png) !important; /** sprite-ref: sprites; */
}

.icon-logging {
	background-image: url(../images/data_scroll.png) !important; /** sprite-ref: sprites; */
}

Der erste Kommentar (/** sprite:…) gibt den Namen (sprites), den Pfad für das Masterbild (../images/sprites.png) sowie das Layout (vertical) an. Mit dieser Konfiguration wird ein Masterbild mit Namen sprites.png angelegt und die einzelnen Icons werden darin vertikal abgelegt. Anstatt vertikal können die Bilder auch horizontal angeordnet werden.

Bei jedem Bild wird mit /** sprite-ref: sprites; */ konfiguriert in welches Masterbild dieses Icon eingefügt werden soll.
Damit ist es möglich mehrere Masterbilder anzulegen, zum Beispiel eins für alle PNG und eins für alle GIF.

Nun benötigen wir eine Möglichkeit um den SmartSprites Prozessor zu starten. Man kann SmartSprites von der Kommandozeile starten und für Ant Projekte wird ein entsprechender Task mitgeliefert. Für Maven gibt es kein Plugin, aber mit dem maven-antrun-plugin lässt sich SmartSprites trotzdem relativ einfach integrieren.

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-antrun-plugin</artifactId>
	<version>1.7</version>
	<executions>
		<execution>
			<id>generate-resources</id>
			<phase>generate-resources</phase>
			<configuration>
				<target>

					<taskdef resource="smartsprites.xml">
						<classpath refid="maven.plugin.classpath" />
					</taskdef>

					<smartsprites rootdir="${basedir}/src/main/webapp/resources/css" 
								  cssfileencoding="UTF-8" cssfilesuffix="-sprite"
								  loglevel="INFO" spritepngdepth="AUTO" 
								  spritepngie6="false" />


				</target>
			</configuration>
			<goals>
				<goal>run</goal>
			</goals>
		</execution>
	</executions>
	<dependencies>
		<dependency>
			<groupId>com.carrotsearch</groupId>
			<artifactId>smartsprites</artifactId>
			<version>0.2.8</version>
		</dependency>
	</dependencies>
</plugin>

Gesteuert wird SmartSprites mit dem <smartsprites> Tag. SmartSprites sucht nach Dateien mit der Endung *.css im angegebenen rootdir Verzeichnis und in allen Unterverzeichnissen. Das Programm überschreibt nicht die Original css Datei sondern erstellt eine Datei mit dem gleichen Namen und dem Suffix das unter cssfilesuffix angegeben ist. Wenn die Original Datei app.css heisst wird das verarbeitete File app-sprite.css heissen und im gleichen Verzeichnis wie das Original abgespeichert. Eine genaue Beschreibung aller Optionen findet man auf der Homepage des Projektes.

Im Beispiel ist das Plugin der generate-resources Phase angehängt und kann mit dem Aufruf von mvn generate-resources ausgeführt werden. SmartSprites sucht nach den CSS Files, analysiert die Kommentare und erstellt das Masterbild sowie das neue css File.

Nach dem Ausführen des Programms und wenn keine Fehler aufgetreten ist finden wir im gleichen Verzeichnis wie das Original eine *-sprite.css Datei. Das Masterbild befindet sich im konfigurierten Pfad. In diesem Beispiel unter (./src/main/webapp/resources/images/sprites.png).

In der *-sprite.css Datei sehen wir die Änderungen die SmartSprites vorgenommen hat. Alle Kommentare wurden entfernt, background-image referenziert neu das Masterbild und background-position gibt die Position des ursprünglichen Bildes innerhalb des Masterbildes an.

.icon-add {
  background-image: url('../images/sprites.png') !important;
  background-position: left -0px !important;
}

.icon-delete {
  background-image: url('../images/sprites.png') !important;
  background-position: left -16px !important;
}

.icon-logging {
  background-image: url('../images/sprites.png') !important;
  background-position: left -32px !important;
}

Zum Schluss müssen die HTML Seiten angepasst werden, damit sie nicht mehr das Original css sondern das *-sprite.css File referenzieren.

Das hier beschriebene Projekt befindet sich auf Github: Changelog
Dort konnten 32 Bilder in ein Bild zusammengefasst werden.

Weitere Links zu CSS Sprites:
http://www.w3schools.com/css/css_image_sprites.asp
http://www.tutorial9.net/tutorials/web-tutorials/building-faster-websites-with-css-sprites/
http://coding.smashingmagazine.com/2009/04/27/the-mystery-of-css-sprites-techniques-tools-and-tutorials/

Um mit einer Datei zu arbeiten benötigt man als erstes eine Referenz auf ein File. Diese bekommt man entweder von einem file input Tag.

<input id="file" type="file" name="file" multiple>

Im Javascript greift man auf das input Element zu und bekommt mit .files ein Array aller ausgewählten Dateien zurück. Mit der File Referenz kann dann zum Beispiel die Grösse und der Name abgefragt werden.

var myFiles = document.getElementById('file').files;
for (var i = 0; i < myFiles.length; i++) {  
  console.log(myFiles[i].name);
  console.log(myFiles[i].size);
}

Die zweite Möglichkeit an eine Filereferenz zu gelangen ist via Drag and Drop. Eine Beschreibung wie das funktioniert findet man auf der HTML5 Rocks Seite: http://www.html5rocks.com/en/tutorials/file/dndfiles/

Mit der Filereferenz kann nun der Inhalt der Datei eingelesen werden. Dazu benötigt man das Objekt FileReader. FileReader stellt 4 Methoden für das Einlesen zur Verfügung. readAsBinaryString, readAsText, readAsDataURL und reasAsArrayBuffer.

Wie so vieles in Javascript geschieht auch das Einlesen eines Files asynchron. Das heisst man muss einen Eventlistener registrieren damit das Programm informiert wird sobald das Einlesen beendet ist.

Die onload Callback Function wird aufgerufen sobald das File vollständig eingelesen wurden. Das Event enthält im e.target.result den Inhalt der Datei. Das folgende Beispiel zeigt den Dateiinhalt auf der Webseite an.

var reader = new FileReader();
  reader.onload = function(e) {					
    var pre = document.createElement('pre');
    pre.innerHTML = e.target.result;
    document.getElementById('out').insertBefore(pre, null);
  }
  reader.readAsText(myFiles[i]);

Weitere FileReader Events sind:

• loadstart: Wenn das Einlesen startet
• progress: Während des Einlesens. Mit event.loaded und event.total kann der Fortschritt berechnet werden
• abort: Wenn das Einlesen mit der Methode FileReader.abort() abgebrochen wurde
• error: Wenn ein Fehler beim Lesen der Datei auftaucht
• load: Wenn das Einlesen erfolgreich beendet wurde
• loadend: Wenn das Einlesen beendet wurde. Egal ob erfolgreich oder mit einem Fehler

Sorucecode auf Github: https://github.com/ralscha/playground/tree/master/upload

Tomcat ab Version 7 und Jetty ab Version 8 haben Unterstützung für Servlet 3.0 eingebaut und können für folgende Tests eingesetzt werden.

Auf der Seite des Servers müssen wir nun zuerst die Multipart Verarbeitung einschalten. Dies geschieht entweder im File web.xml indem man in der Servletkonfiguration einen <multipart-config/> Tag hinzufügt. Alternativ können die Servlets mit der Annotation MultipartConfig gekennzeichnet werden. Da in Spring MVC ein DispatcherServlet als Frontcontroller eingesetzt wird fügen wir die Konfiguration in der Datei web.xml ein.

<servlet>
  <servlet-name>appServlet</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
  <init-param>
    <param-name>contextConfigLocation</param-name>
    <param-value></param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
  <multipart-config/>
</servlet>

Das Hinzufügen des Tags <multipart-config/> genügt damit dass das Servlet Multipart Requests verarbeiten kann. In Jetty 8.1 ist die Verarbeitung auch ohne diese Zeile eingeschaltet. Für den Tomcat Server dagegen muss der Tag vorhanden sein.

Die Multipart Verarbeitung kann mit folgenden Optionen zusätzlich konfiguriert werden.

<multipart-config>
    <file-size-threshold>....</file-size-threshold>
    <location><..../location>
    <max-file-size>....</max-file-size>
    <max-request-size>....</max-request-size>
  </multipart-config>

• fileSizeThreshold: Gibt an nach wievielen Bytes die Datei temporär auf Disk gespeichert wird. Damit soll verhindert werden das grosse Dateiuploads den Speicher zum Überlaufen bringen.
• location: ist ein absoluter Pfad der ein Verzeichnis im Filesystem angibt in dem die Dateien temporär zwischengespeichert werden sobald der fileSizeThreshold erreicht wird.
• maxFileSize: gibt an wie gross ein Upload in Bytes sein darf. Wenn der Upload grösser ist wirft der Container eine Exception.
• maxRequestSize: gibt die maximale Grösse in Bytes an die ein kompletter Request haben darf. Dies ist das Total aller Parts in einem Multipart Request. Auch hier wirft der Container eine Exception wenn die Anzahl Bytes überschritten wird.

Im form Tag muss wie gewohnt der enctype auf multipart/form-data gesetzt sein. Zusätzlich wird ein file input Tag benötigt.

<form action="simpleUpload" method="post" enctype="multipart/form-data">
  <input id="file" type="file" name="file>
  <button type="submit">Upload File(s)</button>
</form>

In der Controller Klasse wird eine Methode eingefügt, die den Post Request verarbeitet. Die Klasse Part wurde mit Servlet 3.0 eingeführt und repräsentiert einen Part des Multipart Requests.

@Controller
public class UploadController {
   	@RequestMapping(value = "/simpleUpload", method = RequestMethod.POST)
	public String processUpload(HttpServletRequest request,
                                    @RequestParam(“file”) Part file)  {
...
}

Dies funktioniert ohne weitere Konfiguration mit Spring. In der Spring 3.1 Dokumentation wird erwähnt das ein StandardServletMultipartResolver benötigt wird.

<bean id="multipartResolver"
class="org.springframework.web.multipart.support.StandardServletMultipartResolver">
</bean>

Dieser wird allerdings nur dann benötigt wenn als Parameter anstatt Part MultipartFile verwendet werden soll. Allerdings hat der MultipartResolver in der aktuellen Version 3.1 einen Fehler der den Einsatz verhindert (siehe Forum Post)

Nachtrag 22.02.2012
Der Fehler im MultipartResolver ist nur bemerkbar in Jetty und Resin. Es funktioniert alles ohne Probleme mit Tomcat und Glassfish. Anstatt Part kann man die Spring Klasse MultipartFile als Parameter verwenden.
Jira-Bug: https://jira.springsource.org/browse/SPR-9149

Ein kleines Problem mit der Part Klasse ist das es keine eingebaute Methode gibt die den Filenamen zurückgibt. Folgende Methode löst dieses Problem und liest den Dateinamen aus dem Header.

Nachtrag 22.02.2012
Die Klasse MultipartFile enthält die Method getOriginalFilename() die den Filenamen zurückgibt.

private String getFileName(Part part) {
  String partHeader = part.getHeader("content-disposition");

  for (String cd : partHeader.split(";")) {
    if (cd.trim().startsWith("filename")) {
      return cd.substring(cd.indexOf('=') + 1).trim().replace("\"", "");
    }
  }
  return null;
}

Der Input File Tag erlaubt es auch das Attribute multiple anzugeben.

<input id="file" type="file" name="file" multiple>

Der User kann nun mehrere Dateien auswählen und übermitteln. In dem Fall funktioniert die Methode mit dem Parameter nicht mehr, da alle Dateien den gleichen Partnamen besitzen. Mit der Methode getParts des HttpServletRequest Objekts kann aber auf eine Collection der Parts eines Multipart Requests zugegriffen werden.

Anstatt

public String processUpload(HttpServletRequest request,
@RequestParam(“file”) Part file)   {
...
}

kann dieser Code verwendet werden um Zugriff auf die Dateien zu erlangen.

public String processUpload(HttpServletRequest request)   {
  for (Part part : request.getParts()) {
     String fileName = getFileName(part);
     if (fileName != null) {
        //a file
     }
  }
}

Beachten muss man hier das ein Part entweder eine Datei oder einen Parameter enthalten kann. Jeder Form Parameter erhält seinen eigenen Part im Request. Mit der Prüfung auf den Filenamen wird unterschieden ob es sich um einen Parameter- oder um einen Datei-Part handelt.

Nachtrag 22.02.2012
Die Übermittlung mehrerer Files funktioniert ohne Probleme mit Tomcat und Glassfish. Dazu muss nur eine Liste als Parameter angeben werden
@RequestParam(value = “multipleFiles”, required = false) List<MultipartFile> files)
Siehe Bug https://jira.springsource.org/browse/SPR-9149

Ein weiteres Problem gibt es in Jetty. Gemäss Servlet 3.0 Spezifikaton muss jeder form-data Part ohne Dateiname als Parameter via request.getParameter verfügbar gemacht werden. Leider funktioniert dies im Jetty nicht. Der Tomcat hat damit keine Probleme und liefert die gewünschten Daten zurück wenn man request.getParamter("…") aufruft.

Eine Spring Controller Method die zum Beispiel so aussieht wird also im aktuellen Jetty nicht funktionieren. Spring wirft eine Exception da die Parameter fehlen.

@RequestMapping(value = "/upload", method = RequestMethod.POST)
	public void processUpload(HttpServletRequest request, HttpServletResponse response,
			@RequestParam("chunkNumber") Integer chunkNumber,
			@RequestParam("resumableChunkSize") Long chunkSize) {
}

Als Workaround kann die request.getParts(String name) Methode verwendet werden. Diese gibt den Part mit dem angegeben Namen zurück. Mit getInputStream() erhält man Zugriff auf den Inhalt des Parts und kann diesen in einen String umwandeln. Das folgende Beispiel verwendet die ByteStreams Klasse aus der Google Guava Library.

chunkNumber = Integer.valueOf(getPartString(request, "chunkNumber"));
chunkSize = Long.valueOf(getPartString(request, "resumableChunkSize"));

private String getPartString(HttpServletRequest request, String name) throws IOException, ServletException {
		return new String(ByteStreams.toByteArray(request.getPart(name).getInputStream()));
	}

Sourcecode auf Github: https://github.com/ralscha/spring-playground/tree/master/upload