2 Writing HK2 Components

HK2 Component Model

The Hundred-Kilobyte Kernel (HK2) provides a module system and component model for building complex software systems. HK2 forms the core of GlassFish Server's architecture.

The module system is responsible for instantiating classes that constitute the application functionality. The HK2 runtime complements the module system by creating objects. It configures such objects by:

• Injecting other objects that are needed by a newly instantiated object

• Injecting configuration information needed for that object

• Making newly created objects available, so that they can then be injected to other objects that need it

Services in the HK2 Component Model

An HK2 service identifies the building blocks or the extension points of an application. A service is a plain-old Java object (POJO) with the following characteristics:

• The object implements an interface.

• The object is declared in a JAR file with the META-INF/services file.

To clearly separate the contract interface and its implementation, the HK2 runtime requires the following information:

• Which interfaces are contracts

• Which implementations of such interfaces are services

Interfaces that define a contract are identified by the org.jvnet.hk2.annotations.Contract annotation.

@Retention(RUNTIME)
@Target(TYPE)
public @interface Contract {
}

Implementations of such contracts should be identified with an org.jvnet.hk2.annotations.Service annotation so that the HK2 runtime can recognize them as @Contract implementations.

@Retention(RUNTIME)
@Target(TYPE)
public @interface Service {
    ...
}

For more information, see Service.

HK2 Runtime

Once Services are defined, the HK2 runtime can be used to instantiate or retrieve instances of services. Each service instance has a scope, specified as singleton, per thread, per application, or a custom scope.

@Contract
public abstract class Scope {
    public abstract ScopeInstance current();
}

@Service
public Singleton implements Scope {
    ...
}

@Scope(Singleton.class)
@Service
public class SingletonService implements RandomContract {
    ...
}

public <T> T getComponent(Class<T> clazz) throws ComponentException;

@Service(name="com.example.container.MyContainer")
public class MyContainer implements Container, PostConstruct, PreDestroy {
    @Inject
    Logger logger;
    ...
    public void postConstruct() {
        logger.info("Starting up.");
    }

    public void preDestroy() {
        logger.info("Shutting down.");
    }
}
    

Inversion of Control

Inversion of control (IoC) refers to a style of software architecture where the behavior of a system is determined by the runtime capabilities of the individual, discrete components that make up the system. This architecture is different from traditional styles of software architecture, where all the components of a system are specified at design-time. With IoC, discrete components respond to high-level events to perform actions. While performing these actions, the components typically rely on other components to provide other actions. In an IoC system, components use injection to gain access to other components.

@Inject
ConfigService config;

@Inject
public void set(ConfigService svc) {...}

@Inject(Scope=Singleton.class, name="deploy")
AdminCommand deployCommand;

@Contract
public interface Startup {...}

Iterable<Startup> startups;
startups = habitat.getComponents(Startup.class);

@Service
public class DeploymentService implements Startup {
    @Inject
    ConfigService config;
}

@Service
public Class ConfigService implements ... {...}

Identifying a Class as an Add-On Component

GlassFish Server discovers add-on components by identifying Java programming language classes that are annotated with the org.jvnet.hk2.annotation.Service annotation.

To identify a class as an implementation of an GlassFish Server service, add the org.jvnet.hk2.annotations.Service annotation at the class-definition level of your Java programming language class.

@Service
public class SamplePlugin implements ConsoleProvider {
...
}

The @Service annotation has the following elements. All elements are optional.

name

The name of the service. The default value is an empty string.

scope

The scope to which this service implementation is tied. The default value is org.glassfish.hk2.scopes.PerLookup.class.

factory

The factory class for the service implementation, if the service is created by a factory class rather than by calling the default constructor. If this element is specified, the factory component is activated, and Factory.getObject is used instead of the default constructor. The default value of the factory element is org.jvnet.hk2.component.Factory.class.

@Service (name="MyService",
    scope=com.example.PerRequest.class,
    factory=com.example.MyCustomFactory)
public class SamplePlugin implements ConsoleProvider {
...
}

Using the Apache Maven Build System to Develop HK2 Components

If you are using Maven 2 to build HK2 components, invoke the auto-depends plug-in for Maven so that the META-INF/services files are generated automatically during build time.

<plugin>
    <groupId>org.glassfish.hk2</groupId>
    <artifactId>hk2-maven-plugin</artifactId>
    <configuration>
        <includes>
            <include>com/example/**</include>
        </includes>
    </configuration>
</plugin>

package com.example.wallaby.annotations;
@Contract
public interface Startup {...}

package com.example.wombat;
@Contract
public interface RandomContract {...}

package com.example.wallaby;
@Service
public class MyService implements Startup, RandomContract, PropertyChangeListener {
    ...
}

com.example.wallaby.annotations.Startup
com.example.wombat.RandomContract