Converter.java

/*
 * Copyright (c) OSGi Alliance (2008). All Rights Reserved.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.eclipse.virgo.shell;

/**
 * A converter is a service that can help create specific object types from a
 * string, and vice versa.
 * 
 * The shell is capable of coercing arguments to the their proper type. However,
 * sometimes commands require extra help to do this conversion. This service can
 * implement a converter for a number of types.
 * 
 * The command shell will rank these services in order of service.ranking and
 * will then call them until one of the converters succeeds.
 * 
 * TODO The javadoc in this class need a good scrub before release.
 * 
 * @ThreadSafe
 * @version $Revision: 5654 $
 */
public interface Converter {
        /**
         * This property is a string, or array of strings, and defines the classes
         * or interfaces that this converter recognises. Recognised classes can be
         * converted from a string to a class and they can be printed in 3 different
         * modes.
         */
        String CONVERTER_CLASSES = "osgi.converter.classes";

        /**
         * Print the object in detail. This can contain multiple lines.
         */
        int INSPECT = 0;

        /**
         * Print the object as a row in a table. The columns should align for
         * multiple objects printed beneath each other. The print may run over
         * multiple lines but must not end in a CR.
         */
        int LINE = 1;

        /**
         * Print the value in a small format so that it is identifiable. This
         * printed format must be recognisable by the conversion method.
         */
        int PART = 2;

        /**
         * Convert an object to the desired type.
         * 
         * Return null if the conversion can not be done. Otherwise return and
         * object that extends the desired type or implements it.
         * 
         * @param desiredType The type that the returned object can be assigned to
         * @param in The object that must be converted
         * @return An object that can be assigned to the desired type or null.
         * @throws Exception
         */
        Object convert(Class<?> desiredType, Object in) throws Exception;

        /**
         * Convert an object to a CharSequence object in the requested format. The
         * format can be INSPECT, LINE, or PART. Other values must throw
         * IllegalArgumentException.
         * 
         * @param target The object to be converted to a String
         * @param level One of INSPECT, LINE, or PART.
         * @param escape Use this object to format sub ordinate objects.
         * @return A printed object of potentially multiple lines
         * @throws Exception
         */
        CharSequence format(Object target, int level, Converter escape)
                        throws Exception;
}