It is what it is

So far the annotation API in Reflext was using the runtime API to provide annotation access. What I call the runtime API is what most of developers are used to when dealing with annotations.

When using the java.lang.reflect runtime, this works perfectly as the runtime provides obviously runtime annotation. Nothing special here. However at compile time, this runtime access is emulated by the compiler. The real API to access an annotation is the java.lang.model.element.AnnotationMirror interface that is a totally detyped access to an annotation. But the APT tries to be nice and provides an emulation of runtime annotation that works well until

• the introspected annotation is being compiled and it is not yet available under its class form
• the annotation is already compiled (coming likely from JDK or a dependency) but it has a Class parameter and that class is being compiled. In that situation the Class object is not yet available, consequently it fails.

For that matter there is now in Reflext an API that provides a detyped access to an annotation that works equally with runtime and compile time implementations (runtime annotation access is still possible of course) .Using such API is obviously less intuitive than using the annotation directly but when you don’t have the guarantee that you are the annotation type is already compiled it’s the only way to go.

We have just released CRaSH 1.0.0 Beta 8 on Google Code forge, in that release we have worked on two usability aspects of the shell:

• The capability for a command to prompt a value with or without echo of the value entered by the user. It is mainly used by the connect command to prompt the password when it is not entered via the -p option.
• The second feature is the up/down arrow associated to recalling previously entered commands.

Just released the 1.0.0-beta3 release of CRaSH, you can get it there.

The first and foremost new features in that release are contributed by Patrice Lamarque that gave us very important commands such as cp to copy a JCR node, mv to move a JCR node and xpath to perform an xpath query in a similar way you can perform a SQL query.

Beside that, the pwd command was bugged in beta2 and is fixed in beta3.

The embbeded type support for Chromattic brings much power to object modeling on top of Java Content Repository that allows to fully take advantage of how JCR models node types. JCR type model provides two features that don’t match the Java type mode.

The first feature is multiple inheritance that is supported natively by JCR which allows a type to extend several super types. The other feature is the mixin support which is pretty much similar to multiple inheritance except that it can be dynamic, meaning that a node can be assigned with a mixin type. Conversely a mixin type can be removed from a node.

Both features are difficult with classic Java inheritance and the most appropriate way for modeling those is to leverage object delegation. Actually often object delegation is preferable over inheritance as it decouples the object types and provides support for dynamicity.

Mixin type support

The following example is taken from GateIn and it shows how several java type can support templatization with the embedded support.

The Templatized class is a delegate object that provides a relationship to a Template type.

@MixinType(name="templatized")
public abstract class Templatized {

  @OneToMany(type=RelationshipType.PATH)
  @MappedBy("template")
  public abstract Template getTemplate();
  public abstract void setTemplate(Template template);

}

The Page class has an embedded relationship with a Templatized type.

@PrimaryType(name="page")
public abstract class Page {

  // Returns null if the mixin is not present
  @OneToOne(type=RelationshipType.EMBEDDED)
  public abstract Templatized getTemplatized();

  // Controls the life cycle of the mixin
  public abstract void setTemplatized(Templatized templatized);
}

At runtime this would likely be used in the following manner:

Page page = session.findByPath(Page.class, "page");
Templatized templatized = session.create(Templatized.class);
page.setTemplatized(templatized);
Template template = session.findByPath("template");
templatized.setTemplate(template);

Primary type support

Likewise Chromattic supports primary type, the only difference is that the dynamicity aspect does not occur therefore the relationship always exists between the types and it is obviously not possible to destroy it. This feature provides to my opinion a very good alternative for reusability.

Supports in GateIn

The embedded type feature has been added for GateIn in order to allow the Model Object for Portal (MOP). Indeed the model itself does not care about certain aspects and the portal needs to be able to make the base model richer than it is. With the embedded type we have the opportunity to keep the base model simple and have GateIn add its own mixins such as security, templatization, etc… Likewise eXo WCM that is built on top of GateIn will be able to add its own mixins for the purpose of web content management.

The CRaSH 1.0.0 Beta 2 has been released, you can download it there and the documentation has been updated with the new features.

The most important feature brought by that release is the brand new support for SSH thanks to the Apache SSHD project. SSH access is more suitable for remote access on public networks and SCP can be used to import or export content from the repository.

Configuration is now possible via the web.xml file and the following can be configured:

• SSH username, password, port and key file
• Telnet port

I came across the generics self-bounding pattern, thanks to Olivier’s blog [in french] that uses it to describe fluent extensible interfaces. After a bit of research I found a very interesting forum thread that was talking about that pattern more in depth, in particular how it is possible to extend the pattern to a couple of classes.

Let’s just start with a simple example, a binary tree class:

abstract class Node<E extends Node<E>> {
   public E left;
   public E right;
}

class FooNode extends Node<FooNode> {
}

class BarNode extends FooNode {
}

class JuuNode extends Node<JuuNode> {
}

With that design, we constraint the Node class to be subclasses and have its children to be a subclass of its own subclass, and now we can write:

FooNode root = new FooNode();
root.left = new FooNode();
root.right = new BarNode();

But that is not possible:

FooNode root = new FooNode();
root.left = new JuuNode();

If you have carefully read the forum thread, someone posted an interesting extension of the pattern that uses two classes.

The Reflext framework I started to write a few months ago was using a visitor pattern to visit a set of types. There are several ways to visit a set of types, one of them is to visit the class hierarchy of super classes and implemented interfaces. There are many ways to implement the visitor pattern, one of them relies on decoupling the visitor from the code (or strategy) that takes care of doing the visit. The main interest is to reuse the visiting strategy many times and avoid the visitor to care about how visit is done, the visitor only cares about the overall strategy.

Based on this assumption, we can define two interfaces named Visitor and VisitorStrategy that will vary together, as it makes sense to use a hierarchy visitor with the hierarchy visitor strategy. Let’s start with the base interfaces. We use it a Type object as visited object, in the reflext framework it’s a TypeInfo interface that represents a type (which can be either runtime reflection or APT compile time reflection).

interface Visitor<V extends Visitor<V,S>, S extends Strategy<V,S>> {
  // The interface is empty as the base visitor does not provide an API
}

interface Strategy<V extends Visitor<V,S>, S extends Strategy<V,S>> {
  void visit(Type type, V visitor);
}

Now we can define the hierarchy visitor and its strategy

interface HierarchyVisitor<T extends HierarchyVisitor<T>> extends
  Visitor<T, HierarchyStrategy<T>> {

  // The API for hierarchy visit
  void enter(Type type);
  void leave(Type type);
}

abstract class HierarchyStrategy<T extends HierarchyVisitor<T>> extends
  Strategy<T, HierarchyStrategy<T>> {
  public void visit(Type type, T visitor) {

    // We only accept type which are java classes
    if (type instanceof Class) {
      if (accept(type)) {

        // Visitor callback
        enter(type);

        // Now visit the super class if we have one
        Class clazz = (Class)type;
        Class superClazz = clazz.getSuperClass();
        if (superClazz != null) {
          visit(superClazz, visitor);
        }

        // And now visit the interfaces
        for (Class itf : clazz.getInterfaces()) {
          visit(itf);
        }

        // Visitor callback
        leave(type);
      }
    }
  }
  abstract boolean accept(Type type);
}

We can see that the hierarchy visitor and its strategy vary together because they are constrained by design. The last piece missing is the to make vary the strategy (otherwise we would make the visitor and its strategy the same class…). We do it via an enum that provides several strategies

enum HierarchyScope {
  ALL() {
    public <T extends HierarchyVisitor<T>> HierarchyStrategy<T> get() {
      return new HierarchyStrategy<T>() {
        public boolean accept(Type type) {
          return true;
        }
      }
    }
  },

  ANCESTORS() {
    public <T extends HierarchyVisitor<T>> HierarchyStrategy<T> get() {
      return new VisitorStrategy<T>() {
        public boolean accept(Type type) {
          return (type instanceof Class) && !((Class)type).isInterface());
        }
      }
    }
  };

  public abstract <T extends HierarchyVisitor<T>> HierarchyStrategy<T> get();

}

Et voilà, now we can use safely the visitor. I’m not convinced that is a great piece of software, I’m just sure that it was very fun to write and research. Without the mentioned blogs and my favorite IDE (Intellij IDEA) it would have been nearly impossible to write correctly :-).

Self-bounding generics is a curious beast, it’s even called there “That Recursive Java Generics Thing”. Have fun!

At the beginning of the year I started to write management capabilities in eXo Portal. It already had some management features but it was not really in a usable shape, it was indeed exposing every service of the kernel on the JMX registry, which was very confusing because it was exposing too much information and not the right information, it was just not usable.

Usability is word that matter, even in management, so my idea was, let’s expose management in a usable way. So I went on designing a way to expose management information based on Java annotations (well it’s pretty obvious to do that isn’t it?).

An important point was also to not tie the management to JMX. Indeed even if JMX is the kind of standard for exposing management in Java, I wanted to be able to expose the same management interface using Rest. The idea is to leverage the gadget server of GateIn and provide management information to gadgets.

So I went on designing the management contract (Java 5 annotations) that are agnostic of the management layer. Of course this is not enough for exposing the management in JMX nor in Rest. So we do have custom JMX annotations that describe how a management interface should be exposed in the JMX registry.

Here is an example of a managed service:

@Managed
@NameTemplate({@Property(key = "service", value = "cache"),
@Property(key = "name", value = "{Name}")})
@ManagedDescription("The Cache")
public interface Cache

   @Managed
   @ManagedName("Name")
   @ManagedDescription("The cache name")
   public String getName();

   @Managed
   @ManagedDescription("Evict all entries of the cache")
   public void clearCache();

   ...

}

The @Managed, @ManagedName and @ManagedDescription are the agnostic annotations. The @NameTemplate is an annotation that has only a sense for the JMX layer. The @Managed* annotations really focus on giving a clear and non programmatic description of the management interface.

There a few more features in the framework such an @ManagedBy annotation to specify a delegate for management interface to avoid to clutter the service with management, a ManagementAware interface for programmatically registering new managed object, a management context facility for correctly scoping managed resources (so several instances of the same service can be registered several times with different names in a transparent manner).

Recently I spent time to develop in the kernel layer the plugability for management provider. It is still in the trunk so nothing is really commited yet in GateIn. This plugability allowed my to write the Rest management provider in GateIn. It was also a good way for me to learn a bit more about JAX-RS (many thanks to Stephane that came a few weeks ago at the Mars JUG to talk about Rest and also for helping me a bit tonight ). So I’m still not yet a Rest expert but I have a few bits of management stuff coming to Rest:

@Managed
@NameTemplate({@Property(key = "service", value = "cache"),
@Property(key = "name", value = "{Name}")})
@ManagedDescription("Exo Cache")
@Rest("cache")
public interface Cache
{
   ...
}

The @Rest (it’s not yet definitive) expose the management interface on the Rest connector. For now I’m only considering JSON in my experiment.

management returns a list of the managed services annotated with the @Rest annotation,
aka “resource list”
/management/{resource} returns the management interface description, for instance in our case
we have {name:”cache”,description:”The Cache”,properties:[{name:"Name", description:
"The cache name"}],methods:[{name:"clearCache",description:"Evict all entries of the
cache"}]}

The good news is that we have already plenty of useful management interface in GateIn that were developed a few months ago by our team and all those will be soon available via Rest!!!

Le Mars JUG fera son inauguration le jeudi 15 octobre 2009 lors de l’Agile Tour.

Emmanuel Bernard a accepté d’être le parrain du JUG et cela nous fait très plaisir, il sera aussi le premier conférencier du JUG et nous parlera d’Hibernate Search, un projet qui permet de faire des requetes full-texte tout en utilisant Hibernate. Il explorera entre autre comment les recherches approximatives telles que la recherche phonetique sont implementées.

Les passionnés d’Agilité et de Java seront comblés car le JUG s’est associé à l’Agile Tour (participation gratuite, inscription ici) pour l’inauguration. Le but est de créer une synergie entre les deux évènements qui sont en général assez rare dans la région PACA. Je tiens à remercier Viaxoft et plus particulièrement Karine pour cette collaboration.

Dimitri Rodolphe Baeli un collègue d’eXo Platform sera lui présent mais durant l’Agile Tour pour faire un tour des pratiques TDD en entreprise.

Le but du Mars JUG est de fédérer autour de Java et de créer une communauté dans notre région, j’espère que vous répondrez présent à l’appel le 15 octobre.