--- a/jdk/src/share/classes/com/sun/jmx/namespace/serial/RewritingProcessor.java Wed Oct 21 16:28:57 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,362 +0,0 @@
-/*
- * 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);
- }
-
-}