*         fully added.
     */
    public Action addAction(Action action) {

        // if no object ref we bail early.
        if (action.getPObjectReference() == null) {
            logger.severe("Addition of action was rejected null Object reference "
                    + action);
            return null;
        }

        // gen instance of state manager
        StateManager stateManager = library.getStateManager();

        // check if there is a 'dest' entry, if so we need to add this as a new
        // action, flag it for later processing.
        boolean isDestKey = getObject(LinkAnnotation.DESTINATION_KEY) != null;

        // check the annotation dictionary for an instance of an existing action
        if (getObject(ACTION_KEY) != null) {
            // if found we will add the new action at the beginning of the
            // next chain.
            boolean isReference = library.isReference(getEntries(),
                    ACTION_KEY.toString());
            // we have a next action that is an object, mark it for delete.
            // Because its a reference no need to flag the annotation as changed.
            if (isReference) {
                // mark this action for delete.
                Action oldAction = (Action) action.getObject(ACTION_KEY);
                oldAction.setDeleted(true);
                stateManager.addChange(new PObject(oldAction,
                        oldAction.getPObjectReference()));
            }
            // not a reference, we have an inline dictionary and we'll be
            // clearing it later, so we only need to add this annotation
            // to the state manager.
            else {
                getEntries().remove(ACTION_KEY);
                stateManager.addChange(new PObject(this, getPObjectReference()));
            }
        }
        // add the new action as per usual
        getEntries().put(ACTION_KEY, action.getPObjectReference());
        stateManager.addChange(new PObject(this, getPObjectReference()));

        // if this is a link annotation and there is a dest, we need to remove
        // as it is not allowed once an action has bee added.
        if (isDestKey && this instanceof LinkAnnotation) {
            // remove the dest key from the dictionary
            this.getEntries().remove(LinkAnnotation.DESTINATION_KEY);
            // mark the annotation as changed.
            stateManager.addChange(new PObject(this, getPObjectReference()));
        }

        // add the new action to the state manager.
        action.setNew(true);
        stateManager.addChange(new PObject(action, action.getPObjectReference()));
        // add it to the library so we can get it again. 
        library.addObject(action, action.getPObjectReference());

        return action;
    }