public LoggingInstance getLoggingInstance() {
    return (LoggingInstance) getInstance(LoggingInstance.class);
  }

  // operations ///////////////////////////////////////////////////////////////

  /**
   * instructs the main path of execution to continue by taking the default 
   * transition on the current node.
   * @throws IllegalStateException if the token is not active.
   */
  public void signal() {
    if ( hasEnded() ) {
      throw new IllegalStateException("couldn't signal token : token has ended");
    }
    rootToken.signal();
  }

  /**
   * instructs the main path of execution to continue by taking the specified 
   * transition on the current node.
   * @throws IllegalStateException if the token is not active.
   */
  public void signal(String transitionName) {
    if ( hasEnded() ) {
      throw new IllegalStateException("couldn't signal token : token has ended");
    }
    rootToken.signal(transitionName);
  }

  /**
   * instructs the main path of execution to continue by taking the specified 
   * transition on the current node.
   * @throws IllegalStateException if the token is not active.
   */
  public void signal( Transition transition ) {
    if ( hasEnded() ) {
      throw new IllegalStateException("couldn't signal token : token has ended");
    }
    rootToken.signal(transition);
  }

  /**
   * ends (=cancels) this process instance and all the tokens in it.
   */
  public void end() {
    // end the main path of execution
    rootToken.end();
    
    if (end==null) {
      // mark this process instance as ended
      end = Clock.getCurrentTime();
      
      // fire the process-end event
      ExecutionContext executionContext = new ExecutionContext(rootToken);
      processDefinition.fireEvent(Event.EVENTTYPE_PROCESS_END, executionContext);
      
      // add the process instance end log
      rootToken.addLog(new ProcessInstanceEndLog());

      // check if this process was started as a subprocess of a super process
      if (superProcessToken!=null) {
        addCascadeProcessInstance(superProcessToken.getProcessInstance());

        
        ExecutionContext superExecutionContext = new ExecutionContext(superProcessToken);
        superExecutionContext.setSubProcessInstance(this);
        superProcessToken.signal(superExecutionContext);
      }

      // make sure all the timers for this process instance are cancelled when the process end updates get saved in the database.
      // TODO route this directly through the jobSession.  just like the suspend and resume.
      // NOTE Only timers should be deleted, messages-type of jobs should be kept. 
      SchedulerService schedulerService = (SchedulerService) Services.getCurrentService(Services.SERVICENAME_SCHEDULER, false);
      if (schedulerService!=null) schedulerService.deleteTimersByProcessInstance(this);
    }
  }

  /**
   * suspends this execution.  This will make sure that tasks, timers and 
   * messages related to this process instance will not show up in database 
   * queries.
   * @see #resume() 
   */
  public void suspend() {
    isSuspended = true;
    rootToken.suspend();
  }

  /**
   * resumes a suspended execution.  All timers that have been suspended might fire 
   * if the duedate has been passed.  If an admin resumes a process instance, the option 
   * should be offered to update, remove and create the timers and messages related to 
   * this process instance.
   * @see #suspend()
   */
  public void resume() {
    isSuspended = false;
    rootToken.resume();
  }

  // runtime actions //////////////////////////////////////////////////////////

  /**
   * adds an action to be executed upon a process event in the future.
   */
  public RuntimeAction addRuntimeAction( RuntimeAction runtimeAction ) {
    if (runtimeAction == null) throw new IllegalArgumentException("can't add a null runtimeAction to a process instance");
    if (runtimeActions == null) runtimeActions = new ArrayList();
    runtimeActions.add(runtimeAction);
    runtimeAction.processInstance = this;
    return runtimeAction;
  }

  /**
   * removes a runtime action.
   */
  public RuntimeAction removeRuntimeAction( RuntimeAction runtimeAction ) {
    RuntimeAction removedRuntimeAction = null;
    if (runtimeAction == null)
      throw new IllegalArgumentException("can't remove a null runtimeAction from an process instance");
    if (runtimeActions != null) {
      if (runtimeActions.remove(runtimeAction)) {
        removedRuntimeAction = runtimeAction;
        runtimeAction.processInstance = null;
      }
    }
    return removedRuntimeAction;
  }

  /**
   * is the list of all runtime actions.
   */
  public List getRuntimeActions() {
    return runtimeActions;
  }

  // various information retrieval methods ////////////////////////////////////

  /**
   * tells if this process instance is still active or not.
   */
  public boolean hasEnded() {
    return ( end != null );
  }
  
  /**
   * calculates if this process instance has still options to continue. 
   */
  public boolean isTerminatedImplicitly() {
    boolean isTerminatedImplicitly = true;
    if ( end == null ) {
      isTerminatedImplicitly = rootToken.isTerminatedImplicitly();
    }
    return isTerminatedImplicitly;
  }
  
  /**
   * looks up the token in the tree, specified by the slash-separated token path.
   * @param tokenPath is a slash-separated name that specifies a token in the tree.
   * @return the specified token or null if the token is not found.
   */
  public Token findToken(String tokenPath) {
    return ( rootToken!=null ? rootToken.findToken(tokenPath) : null );
  }
  
  /**
   * collects all instances for this process instance.
   */
  public List findAllTokens() {
    List tokens = new ArrayList();
    tokens.add(rootToken);
    rootToken.collectChildrenRecursively(tokens);
    return tokens;
  }

  void addCascadeProcessInstance(ProcessInstance cascadeProcessInstance) {
    if (cascadeProcessInstances==null) {
      cascadeProcessInstances = new ArrayList();
    }
    cascadeProcessInstances.add(cascadeProcessInstance);
  }
  
  public Collection removeCascadeProcessInstances() {
    Collection removed = cascadeProcessInstances;
    cascadeProcessInstances = null;
    return removed;
  }
  
  // equals ///////////////////////////////////////////////////////////////////
  // hack to support comparing hibernate proxies against the real objects
  // since this always falls back to ==, we don't need to overwrite the hashcode
  public boolean equals(Object o) {
    return EqualsUtil.equals(this, o);
  }
  
  // getters and setters //////////////////////////////////////////////////////

  public long getId() {
    return id;
  }
  public Token getRootToken() {
    return rootToken;
  }
  public Date getStart() {
    return start;
  }
  public Date getEnd() {
    return end;
  }
  public Map getInstances() {
    return instances;
  }
  public ProcessDefinition getProcessDefinition() {
    return processDefinition;
  }
  public Token getSuperProcessToken() {
    return superProcessToken;
  }
  public void setSuperProcessToken(Token superProcessToken) {
    this.superProcessToken = superProcessToken;
  }
  public boolean isSuspended() {
    return isSuspended;
  }
  public int getVersion() {
    return version;
  }
  public void setVersion(int version) {
    this.version = version;
  }
  public void setEnd(Date end) {
    this.end = end;
  }
  public void setProcessDefinition(ProcessDefinition processDefinition) {
    this.processDefinition = processDefinition;
  }
  public void setRootToken(Token rootToken) {
    this.rootToken = rootToken;
  }
  public void setStart(Date start) {
    this.start = start;
  }
  /** a unique business key */
  public String getKey() {
    return key;
  }
  /** set the unique business key */
  public void setKey(String key) {
    this.key = key;
  }

  // private static Log log = LogFactory.getLog(ProcessInstance.class);
}