--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/com/sun/jmx/namespace/serial/RewritingProcessor.java Thu Sep 04 14:46:36 2008 +0200
@@ -0,0 +1,362 @@
+/*
+ * 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);
+ }
+
+}