/*
 * Copyright 2008 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 */

package com.sun.jmx.namespace.serial;


import javax.management.ObjectInstance;
import javax.management.ObjectName;

/**
 * An object that can rewrite ObjectNames contained in input/output
 * parameters when entering/leaving a {@link javax.management.namespace
 * namespace}.
 * <p>When entering a {@link javax.management.namespace
 *    namespace}, the {@code namespace} prefix is stripped from
 *    ObjectNames contained in input parameters. When leaving a
 *    {@code namespace},
 *    the {@code namespace} prefix is prepended to the ObjectNames contained in
 *    the result parameters returned from that {@code namespace}.
 * </p>
 * <p>Objects that need to perform these operations usually use a
 *    {@code RewritingProcessor} for that purpose.<br>
 *    The {@code RewritingProcessor} allows a somewhat larger
 *    transformation in which part of a prefix {@link #newRewritingProcessor
 *    remove} can be replaced by another prefix {@link #newRewritingProcessor
 *    add}. The transformation described above correspond to the case where
 *    {@code remove} is the stripped {@link javax.management.namespace
 *    namespace} prefix (removed when entering the {@code namespace}) and
 *    {@code add} is the empty String {@code ""}.
 *    <br>
 *    It is interesting to note that {@link
 *    javax.management.JMXNamespaces#narrowToNamespace narrowToNamespace}
 *    operations use the inverse transformation (that is, {@code remove} is
 *    the empty String {@code ""} and {@code add} is the {@link
 *    javax.management.namespace namespace} prefix).
 *    <br>
 *    On a more general scale, {@link #rewriteInput rewriteInput} removes
 *    {@link #newRewritingProcessor remove} and the prepend {@link
 *     #newRewritingProcessor add}, and {@link #rewriteOutput rewriteOutput}
 *    does the opposite, removing {@link #newRewritingProcessor add}, and
 *    then adding {@link #newRewritingProcessor remove}.
 *    <br>
 *    An implementation of {@code RewritingProcessor} should make sure that
 *    <code>rewriteInput(rewriteOutput(x,clp),clp)</code> and
 *    <code>rewriteOutput(rewriteInput(x,clp),clp)</code> always return
 *    {@code x} or an exact clone of {@code x}.
 * </p>
 * <p>A default implementation of {@code RewritingProcessor} based on
 * Java Object Serialization can be
 * obtained from {@link #newRewritingProcessor newRewritingProcessor}.
 * </p>
 * <p>
 * By default, the instances of {@code RewritingProcessor} returned by
 * {@link #newRewritingProcessor newRewritingProcessor} will rewrite
 * ObjectNames contained in instances of classes they don't know about by
 * serializing and then deserializing such object instances. This will
 * happen even if such instances don't - or can't contain ObjectNames,
 * because the default implementation of {@code RewritingProcessor} will
 * not be able to determine whether instances of such classes can/do contain
 * instance of ObjectNames before serializing/deserializing them.
 * </p>
 * <p>If you are using custom classes that the default implementation of
 * {@code RewritingProcessor} don't know about, it can be interesting to
 * prevent an instance of {@code RewritingProcessor} to serialize/deserialize
 * instances of such classes for nothing. In that case, you could customize
 * the behavior of such a {@code RewritingProcessor} by wrapping it in a
 * custom subclass of {@code RewritingProcessor} as shown below:
 * <pre>
 * public class MyRewritingProcessor extends RewritingProcessor {
 *      MyRewritingProcessor(String remove, String add) {
 *          this(RewritingProcessor.newRewritingProcessor(remove,add));
 *      }
 *      MyRewritingProcessor(RewritingProcessor delegate) {
 *          super(delegate);
 *      }
 *
 *  <T> T rewriteInput(T input) {
 *          if (input == null) return null;
 *          if (MyClass.equals(input.getClass())) {
 *              // I know that MyClass doesn't contain any ObjectName
 *              return (T) input;
 *          }
 *          return super.rewriteInput(input);
 *      }
 *  <T> T rewriteOutput(T result) {
 *          if (result == null) return null;
 *          if (MyClass.equals(result.getClass())) {
 *              // I know that MyClass doesn't contain any ObjectName
 *              return (T) result;
 *          }
 *          return super.rewriteOutput(result);
 *      }
 * }
 * </pre>
 * </p>
 * <p>Such a subclass may also provide an alternate way of rewriting
 *    custom subclasses for which rewriting is needed - for instance:
 * <pre>
 * public class MyRewritingProcessor extends RewritingProcessor {
 *      MyRewritingProcessor(String remove, String add) {
 *          this(RewritingProcessor.newRewritingProcessor(remove,add));
 *      }
 *      MyRewritingProcessor(RewritingProcessor delegate) {
 *          super(delegate);
 *      }
 *
 *  <T> T rewriteInput(T input) {
 *          if (input == null) return null;
 *          if (MyClass.equals(input.getClass())) {
 *              // I know that MyClass doesn't contain any ObjectName
 *              return (T) input;
 *          } else if (MyOtherClass.equals(input.getClass())) {
 *              // Returns a new instance in which ObjectNames have been
 *              // replaced.
 *              final ObjectName aname = ((MyOtherClass)input).getName();
 *              return (T) (new MyOtherClass(super.rewriteInput(aname)));
 *          }
 *          return super.rewriteInput(input,clp);
 *      }
 *  <T> T rewriteOutput(T result) {
 *          if (result == null) return null;
 *          if (MyClass.equals(result.getClass())) {
 *              // I know that MyClass doesn't contain any ObjectName
 *              return (T) result;
 *          } else if (MyOtherClass.equals(result.getClass())) {
 *              // Returns a new instance in which ObjectNames have been
 *              // replaced.
 *              final ObjectName aname = ((MyOtherClass)result).getName();
 *              return (T) (new MyOtherClass(super.rewriteOutput(aname)));
 *          }
 *          return super.rewriteOutput(result,clp);
 *      }
 * }
 * </pre>
 * </p>
 * <p>If your application only uses {@link javax.management.MXBean MXBeans},
 * or MBeans using simple types, and doesn't define any custom subclass of
 * {@link javax.management.Notification}, you should never write such
 * such {@code RewitingProcessor} implementations.
 * </p>
 * <p><b>
 * This API is a Sun internal API and is subject to changes without notice.
 * </b></p>
 * @since 1.7
 */
public abstract class RewritingProcessor {
    /**
     * A logger for this class.
     **/
    private final RewritingProcessor delegate;

    /**
     * Creates a new instance of RewritingProcessor.
     * <p>This is equivalent to calling {@link
     * #RewritingProcessor(RewritingProcessor) RewritingProcessor(null)}.
     * </p>
     **/
    protected RewritingProcessor() {
        this(null);
    }

    /**
     * Creates a new instance of RewritingProcessor, with a delegate.
     * @param delegate a {@code RewritingProcessor} to which all the
     *        calls will be delegated. When implementing a subclass
     *        of  {@code RewritingProcessor}, calling {@link
     *        #rewriteInput super.rewriteInput} will invoke
     *        {@code delegate.rewriteInput} and calling {@link
     *        #rewriteOutput super.rewriteOutput} will invoke
     *        {@code delegate.rewriteOutput}.
     *
     **/
    protected RewritingProcessor(RewritingProcessor delegate) {
        this.delegate = delegate;
    }

    /**
     * Rewrites ObjectNames when {@link RewritingProcessor leaving} a {@link
     * javax.management.namespace namespace}.
     * <p>
     * Returns {@code obj}, if it is known that {@code obj} doesn't contain
     * any ObjectName, or a new copied instance of {@code obj} in which
     * ObjectNames (if any) will have been rewritten, if {@code obj} contains
     * ObjectNames, or if it is not known whether {@code obj} contains
     * ObjectNames or not.
     * </p>
     * <p>
     * The default implementation of this method is as follows: if the
     * {@link #RewritingProcessor(RewritingProcessor) delegate} is {@code
     * null}, throws an {@link IllegalArgumentException}. Otherwise,
     * returns {@code delegate.rewriteOutput(obj)}.
     * </p>
     * <p>This behavior can be overridden by subclasses as shown in this
     * class {@link RewritingProcessor description}.
     * </p>
     * @param obj The result to be rewritten if needed.
     *
     * @return {@code obj}, or a clone of {@code obj} in which ObjectNames
     *         have been rewritten. See this class {@link RewritingProcessor
     *         description} for more details.
     * @throws IllegalArgumentException if this implementation does not know
     *         how to rewrite the object.
     **/
    public <T> T rewriteOutput(T obj) {
        if (obj == null) return null;
        if (delegate != null)
            return delegate.rewriteOutput(obj);
        throw new IllegalArgumentException("can't rewrite "+
                obj.getClass().getName());
    }

    /**
     * Rewrites ObjectNames when {@link RewritingProcessor entering} a {@link
     * javax.management.namespace namespace}.
     * <p>
     * Returns {@code obj}, if it is known that {@code obj} doesn't contain
     * any ObjectName, or a new copied instance of {@code obj} in which
     * ObjectNames (if any) will have been rewritten, if {@code obj} contains
     * ObjectNames, or if it is not known whether {@code obj} contains
     * ObjectNames or not.
     * </p>
     * <p>
     * The default implementation of this method is as follows: if the
     * {@link #RewritingProcessor(RewritingProcessor) delegate} is {@code
     * null}, throws an {@link IllegalArgumentException}. Otherwise,
     * returns {@code delegate.rewriteInput(obj)}.
     * </p>
     * <p>This behavior can be overridden by subclasses as shown in this
     * class {@link RewritingProcessor description}.
     * </p>
     * @param obj The result to be rewritten if needed.
     * @return {@code obj}, or a clone of {@code obj} in which ObjectNames
     *         have been rewritten. See this class {@link RewritingProcessor
     *         description} for more details.
     * @throws IllegalArgumentException if this implementation does not know
     *         how to rewrite the object.
     **/
    public <T> T rewriteInput(T obj) {
        if (obj == null) return null;
        if (delegate != null)
            return delegate.rewriteInput(obj);
        throw new IllegalArgumentException("can't rewrite "+
                obj.getClass().getName());
    }

    /**
     * Translate a routing ObjectName from the target (calling) context to
     * the source (called) context when {@link RewritingProcessor entering} a
     * {@link javax.management.namespace namespace}.
     * <p>
     * The default implementation of this method is as follows: if the
     * {@link #RewritingProcessor(RewritingProcessor) delegate} is {@code
     * null}, throws an {@link IllegalArgumentException}. Otherwise,
     * returns {@code delegate.toSourceContext(targetName)}.
     * </p>
     * <p>This behavior can be overridden by subclasses as shown in this
     * class {@link RewritingProcessor description}.
     * </p>
     * @param targetName The routing target ObjectName to translate.
     * @return The ObjectName translated to the source context.
     * @throws IllegalArgumentException if this implementation does not know
     *         how to rewrite the object.
     **/
    public ObjectName toSourceContext(ObjectName targetName) {
        if (delegate != null)
            return delegate.toSourceContext(targetName);
        throw new IllegalArgumentException("can't rewrite targetName: "+
               " no delegate.");
    }

    /**
     * Translate an ObjectName returned from the source context into
     * the target (calling) context when {@link RewritingProcessor leaving} a
     * {@link javax.management.namespace namespace}.
     * <p>
     * The default implementation of this method is as follows: if the
     * {@link #RewritingProcessor(RewritingProcessor) delegate} is {@code
     * null}, throws an {@link IllegalArgumentException}. Otherwise,
     * returns {@code delegate.toTargetContext(sourceName)}.
     * </p>
     * <p>This behavior can be overridden by subclasses as shown in this
     * class {@link RewritingProcessor description}.
     * </p>
     * @param sourceName The routing source ObjectName to translate to the
     *        target context.
     * @return The ObjectName translated to the target context.
     * @throws IllegalArgumentException if this implementation does not know
     *         how to rewrite the object.
     **/
    public ObjectName toTargetContext(ObjectName sourceName) {
        if (delegate != null)
            return delegate.toTargetContext(sourceName);
        throw new IllegalArgumentException("can't rewrite sourceName: "+
               " no delegate.");
    }

    /**
     * Translate an ObjectInstance returned from the source context into
     * the target (calling) context when {@link RewritingProcessor leaving} a
     * {@link javax.management.namespace namespace}.
     * <p>
     * The default implementation of this method is as follows: if the
     * {@link #RewritingProcessor(RewritingProcessor) delegate} is {@code
     * null}, throws an {@link IllegalArgumentException}. Otherwise,
     * returns {@code delegate.toTargetContext(sourceMoi)}.
     * </p>
     * <p>This behavior can be overridden by subclasses as shown in this
     * class {@link RewritingProcessor description}.
     * </p>
     * @param sourceMoi The routing source ObjectInstance to translate.
     * @return The ObjectInstance translated to the target context.
     * @throws IllegalArgumentException if this implementation does not know
     *         how to rewrite the object.
     **/
    public ObjectInstance toTargetContext(ObjectInstance sourceMoi) {
        if (delegate != null)
            return delegate.toTargetContext(sourceMoi);
        throw new IllegalArgumentException("can't rewrite sourceName: "+
               " no delegate.");
    }

    /**
     * Creates a new default instance of {@link RewritingProcessor}.
     * @param remove The prefix to remove from {@link ObjectName ObjectNames}
     *        when {@link RewritingProcessor entering} the {@link
     *        javax.management.namespace namespace}.
     * @param add The prefix to add to {@link ObjectName ObjectNames}
     *        when {@link RewritingProcessor entering} the {@link
     *        javax.management.namespace namespace} (this is performed
     *        after having removed the {@code remove} prefix.
     * @return A new {@link RewritingProcessor} processor object that will
     *         perform the requested operation, using Java serialization if
     *         necessary.
     **/
    public static RewritingProcessor newRewritingProcessor(String remove,
            String add) {
        return new DefaultRewritingProcessor(remove,add);
    }

}