@Service
public class LeadBean implements SomeContract {
...
}

@DependentOf(LeadBean.class) 
public class CompanionBean implements SomethingElse {
...
}

@Dependent(LeadBean.class)
public class CompanionBean implements PostConstruct, SomethingElse {

    @Inject
    RandomService random;

    final LeadBean parent;

    public CompanionBean(LeadBean parent) {
        this.parent = parent;
        // random is not available.
        // this is the 1st phase, exceptions can be thrown, 
        // rollbacking the configuration transaction.
    }

    public void postConstruct() {
        // second phase, exceptions still possible.
        // random and parent are available
    }
}

@Dependent(LeadBean.class)
public class CompanionBean implements SomethingElse {

    @Inject
    RandomService random;
    
    @Lead (we should rename this)
    LeadBean parent;

}

@Service
public RandomService implements RandomContract {

    @Inject(dynamic=true)
    Holder<RandomContract> myContract;

    public void foo() {
        myContract.do(); // will always invoke do() on the currently registered service.
    }
}

@Inject(dynamic=true)
RandomContract myContract;

@Service
public RandomService implements RandomContract {

    
    RandomContract myContract;

    @Inject(dynamic=true)
    public void setRandomContract(RandomContract contract) {
        // will be invoked one on construction, and each time the contract is changed 
        // in the registry.
    }
}

@Service
public RandomService implements RandomContract, ConfigListener {
    
   @Inject
   SomeConfig myConfig 

   public PropertyChangeEvents[] changed(List<PropertyChangeEvent> events) { 
        // events represent the list of all applied changes, after the transaction 
        // is committed. 
        // myConfig is ONE of the bean changed, and already points to the new values.
   }

@Service
public RandomService implements RandomContract {

    @Inject
    SomeConfig myConfig;

    @Prepare
    public void prepare(@Inject SomeConfig newConfig) {
	// compare myConfig with newConfig)
    }

    @Commit
    public PropertyChangeEvent[] commit(SomeConfig newConfig) {
	// called after each update
    }

    @Rollback 
    public void rollback() {
	// called after prepare if failure
    }

@Service
public RandomService implements RandomContract {

    @Inject SomeConfig myConfig;
    @Inject OtherConfig otherConfig;

    @Prepare
    public void prepare(@Inject SomeConfig newConfig) {
	// compare myConfig with newConfig)
    }

    @Prepare
    public void prepare(@Inject OtherConfig newConfig) throws TransactionFailure {
	// compare otherConfig with newConfig)
        // throw a transaction failure to abort the configuration change
    }

    @Commit
    public PropertyChangeEvent[] commit(SomeConfig newConfig) {
	// called after each successful transaction
        // cannot throw an exception ,cannot rollback the transaction
        // return the list of unprocessed changes (requiring a restart)
    }

    @Commit
    public PropertyChangeEvent[] commit(OtherConfig newConfig) {
	// called after each transaction success
    }

    @Rollback 
    public void rollback() {
	// if prepare was called and did not throw an exception, 
        // will be called if the transaction is a failure
    }

@DependentOfConfig(Cluster.class)
public class ClusterService implements PostConstruct, PreDestroy {

	@Inject
	RandomService someService;

	final Cluster myConfig;
	DynamicService myDynService;
	
	public ClusterService(Cluster config) {
             // 1st phase
             myConfig = config;
	}
	
	public void postConstruct() {
            // 2nd phase : mySevice are myDynService are available
	}

	public void preDestroy() {
		// myConfig is removed
       }

	@Inject(name="foo", dynamic=true)
	public void setDynService(DynamicService dynService) {
		// called once between constructor and postConstruct)
		// and each time "foo" DynamicService is changed in the ServiceRegistry
		myDynService = dynService;	
	} 
	
	
	@Prepare
	public void prepare(@Inject Cluster newConfig) {
		// compare myConfig with newConfig)
	}

	@Commit
	public PropertyChangeEvent[] commit() {
		// called  after constructor (once !) and after each update
	}

	@Rollback 
	public void rollback() {
		// called after constructor or each prepare if the transaction is aborted 
	}

}

@AdvertisementKeys(keys="$getName()")
@Service
public FooImpl {

    public String getName() {
      ....
    }
}

/**
 * Interface that define the notion of a key provider. Keys
 * will be used to register services in the service registry 
 * aka the habitat
 */
public interface KeysProvider<T>() {

    List<String> for(T instance);

}

@Service(name="random")
public class FooImpl implements KeyProvider<FooImpl> {
     List<String> for(FooImpl instance) {
        assert this==instance;
        List<String> keys = new ArrayList<String>();
        keys.add(instance.getName());
        return keys;
     }
}

public interface Named {
    String getName();
}

@Configured
public interface ClusterConfig extends Named {
   .. some cluster related config methods ...
}

@Configured
public interface ServerConfig extends Named {
   .. some server related config methods ...
}

public class NamedKeysProvider implements KeyProvider<Named> {
     public List<String> for(Named instance) {
        return instance.getName();
     }
}
{{{

Now we need an annotation to qualify who can use this generic provider : 

/**
 * Annotation to qualify a service registration keys provider
 */
public @interface Keys {

    /**
     * @return the key provider implementation class
     */
    Class<? extends KeysProvider> value();
}

@Service
@Keys(NamedKeysProvider.class);
public class FooImpl implements Named {

    public String getName() {
        .. do something really complicated...
        return it;
    }

}

public @interface DependentOf {

   /**
    * @return the type this service is dependent of.
    */
   Class value();
 
   /**
     * @return the key provider implementation class
     */
    Class<? extends KeysProvider> keys();
}

The service implementation can then become : 

@Service
@DependentOf(ClusterConfig.class, keys = ClusterService.KeyProvider.class)
public class ClusterService { 
    @Inject ClusterConfig config;

    // can be called before an instance of ClusterService is even created.
    public final static ClusterService.KeyProvider implements KeyProvider<ClusterConfig>() {
        List<String> for(ClusterConfig config) {
            List<String> keys = new ArrayList<String>();
            // calculate the keys based on the configuration object and 
            // the receiving type : ClusterService
            keys.add(config.getXXX());
            return keys;
        }
    }
}

public @interface OrderedBy {

    public Class<? extends Sorter> value();

}

public interface Sorter<T extends Annotation> {

    public void sort(List<T> elements);
}

public interface InstantiationRecorder<T> {
    /**
     * returns a (double?) linked list of T services in the order
     * T instances were instantiated.
     */
    public LinkedList<T> records();

    /**
     * records a new instance creation
     */
    public void record(T instance);
}

public @interface Recorder {
    public Class<? extends InstantiationRecorder> value();

}
{{{

The class value() of the @Recorder will be looked up in the habitat by its type and no name, therefore it must be a singleton object and serve a unique contract.

Here is an simple example : 

/**
 * Startup interface is a markup interface for all startup services
 * Startup services are run on startup. 
 */
@Recorder(StartupRecorder.class) 
@Contract
public interface Startup {
}

@Service
public class StartupRecoder implements Recorder<Startup> {
    LinkedList<Startup> getRecords();
    // should it be a LinkedList<Inhabitant<Startup>> instead ? 
}

/**
 * meta-annotation to denote a RunLevel type which can be used 
 * by the HK2 startup sequence to look up the annotated 
 * startup services annotated with the annotation annotated
 * by a @RunLevelType. 
 */ 
public @interface RunLevelType {

    /**
     * defines the environment this run-level-type should 
     * apply to
     */
    String value() default "default";
}

@RunLevelType
@OrderedBy(ChainedState.ChainedLevelSorter.class)
public @interface ChainedState {

    Class previous() default Void.class;

    public static class ChainedLevelSorter implements Sorter {
        @Override
        public void sort(List<AnnotatedElement> elements) {
            // simple insertion sort based on previous...
        }
    }

}

// first in the chain
@ChainedState()
public @interface WLSAdmin {
}

@ChainedState(previous=WLSAdmin.class)
public @interface WLSResuming {
}

@ChainedState(previous=WLSResuming.class)
public @interface WLSRunning {
}

@WLSAdmin
public class WLSStartup {
}

@WLSAdmin
public class WLSStartup2 {
}

@WLSRunning
public class WLSRandomService {
}

@RunLevelType()
@OrderedBy(RunLevel.RunLevelSorter.class)
public @interface RunLevel {
    
    int value() default 0;

    public Class<? extends Sorter> sorter() default RunLevelSorter.class;

    public static class RunLevelSorter implements Sorter {

        @Override
        public void sort(List<AnnotatedElement> elements) {
            // ... sort elements based on value...//
        }

    }    
}

@RunLevel(10)
@OrderedBy(AdminLevel.ALSorter.class)
public @interface AdminLevel {

    int priority() default 50;

    public final class ALSorter implements Sorter {
        @Override
        public void sort(List<AnnotatedElement> elements) {
            // ... sort AdminLevel services based on priority ... //
        }
    }
}

@RunLevelType("default")
@OrderedBy(RunLevel.RunLevelSorter.class)
public @interface RunLevel {
    
    int value() default 0;

    public Class<? extends Sorter> sorter() default RunLevelSorter.class;

    public static class RunLevelSorter implements Sorter {

        @Override
        public void sort(List<AnnotatedElement> elements) {
            // ... sort elements based on value...//
        }

    }    
}

@Retention(RetentionPolicy.RUNTIME)
@OrderedBy(RunLevel.RunLevelSorter.class)
public @interface RunningLevel {

    int value();

    public static class RunLevelSorter implements Sorter<RunLevel> {

        @Override
        public void sort(List<RunLevel> elements) {
            // ... sort elements based on value...//
        }

    }
}

@RunLevel(10)
public @interface RunningLevel {
    // running level, does not have priority and all services are considered equals...
}

@AdminLevel
public class SomeStartupService {
}

@AdminLevel(priority=10)
public class SomeOtherStartup {
}

@RunningLevel
public class YetAnotherStartup {
}

/**
 * defines the notion of a run-level when the 
 * hk2 is starting in an "embedded" mode
@RunLevelType("embedded")
public @interface EmbeddedRunLevel {
}

@AdminLevel(30)
@Embedded(20)
@JMSClient
public class JMSStartupService {
}

@Contract
@Singleton
public interface RunLevelService<T> {
  RunLevel currentLevel();

  /**
   * Moves up or down to a particular run level
   **/
  RunLevelWorker proceedTo(RunLevel level, RunLevelServiceListener listener);
}

@Contract
public interface RunLevelWorker {

  void cancel();   // cancel the job (i.e., stop dead in the tracks). This may leave the system in an ambiguous state that will require either a recover to last checkpoint, or a subsequent proceedTo() call issued.

  boolean isCompleted(); // indicated the work has completed (or the cancel is completed if cancel was called)

}

@Contract
public interface RunLevelServiceListener {

  boolean onError(Exception error); // called when error encountered, caller should return true to continue and false to cancel/abort

  void onProgress(RunLevel level); // called when proceedTo()  is called with multiple level "jumps" involved

  void onCompleted(); // used to notify that isCompleted() has been set to true

}

public void mainCode() {
        ...
        goToLevel(AdminLevel.class);
        ...
        goToLevel(RunningLevel.class);
    }