/**
   * must only be called within the write lock. will remove chunks until capacity is no longer
   * reached (i.e. there is room for one more chunk) - this is called by addSourceChunkInternal
   */
  private void ensureCapacity() {
    IModel model = getModel();
    IMessageBuilder sb = null;
    while (isCapacityReached()) {
      if (sb == null) sb = Logger.messageBuilder();
      else sb.clear();

      /*
       * remove the first..
       */
      IChunk toRemove = getRemovalCandidate();
      if (LOGGER.isDebugEnabled() || Logger.hasLoggers(model)) {
        sb.append(toRemove.toString());
        sb.append(" is being removed because capacity has been reached");
        String msg = sb.toString();

        if (LOGGER.isDebugEnabled()) LOGGER.debug(msg);
        if (Logger.hasLoggers(model)) Logger.log(model, Logger.Stream.BUFFER, msg);
      }
      removeSourceChunk(toRemove);
    }

    if (sb != null) MessageBuilderFactory.recycle(sb);
  }
  @Override
  protected IChunk addSourceChunkInternal(IChunk chunkToInsert) {
    if (LOGGER.isDebugEnabled()) LOGGER.debug("attempting to insert " + chunkToInsert);

    /*
     * ok, something will be changing..
     */
    IChunk errorChunk = getErrorChunk();

    /*
     * did something go wrong? set the states..
     */
    if (errorChunk.equals(chunkToInsert)
        || !isValidChunkType(chunkToInsert.getSymbolicChunk().getChunkType())) {
      if (LOGGER.isDebugEnabled())
        LOGGER.debug(getName() + " : " + chunkToInsert + " was error or invalid of chunk type");
      setStateChunk(errorChunk);
      chunkToInsert = null;
    }

    /*
     * all is good, let's set the chunk
     */
    if (chunkToInsert != null) {
      /*
       * are we bumping up against the maximum capacity?
       */
      ensureCapacity();

      double now = ACTRRuntime.getRuntime().getClock(getModel()).getTime();

      double time = Double.MIN_VALUE;

      /*
       * if LRA or LRU, time will be now, if modified, we set it as minimum
       * double value (can't be negative inf because of potential value
       * collisions, see below)
       */
      switch (getEjectionPolicy()) {
        case LeastRecentlyAdded:
        case LeastRecentlyUsed:
        case MostRecentlyAdded:
        case MostRecentlyUsed:
          time = now;
          break;
      }

      /*
       * problem of more than one chunk inserted at the same time (could happen
       * if a production fires multiple adds)
       */
      while (_sourceChunks.containsKey(time) && !chunkToInsert.equals(_sourceChunks.get(time)))
        time += 0.0000001;

      _sourceChunks.put(time, chunkToInsert);
      _times.put(chunkToInsert, time);

      if (LOGGER.isDebugEnabled())
        LOGGER.debug(getName() + " Source Chunks & Times " + _sourceChunks);

      IModel model = getModel();
      if (LOGGER.isDebugEnabled() || Logger.hasLoggers(model)) {
        IMessageBuilder sb = Logger.messageBuilder();
        sb.append(getName())
            .append(" inserted ")
            .append(chunkToInsert.getSymbolicChunk().getName());

        if (LOGGER.isDebugEnabled()) LOGGER.debug(sb.toString());

        Logger.log(model, Logger.Stream.BUFFER, sb);
      }

      chunkInserted(chunkToInsert);
    }

    return chunkToInsert;
  }