View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */ 
16  package org.apache.commons.betwixt.strategy;
17  
18  import java.io.Serializable;
19  
20  import org.apache.commons.betwixt.Options;
21  import org.apache.commons.betwixt.expression.Context;
22  
23  /*** 
24   * <p>Strategy class for string &lt;-&gt; object conversions.
25   * Implementations of this interface are used by Betwixt to perform
26   * string &lt;-&gt; object conversions.
27   * This performs only the most basic conversions.
28   * Most applications will use a subclass.
29   * </p>
30   * <p>It is strongly recommended that (in order to support round tripping)
31   * that <code>objectToString</code> and <code>stringToObject</code>
32   * are inverse functions.
33   * In other words, given the same flavour, context and type the applying 
34   * objectToString to the result of stringToObject should be equal to the 
35   * original input.
36   * </p>
37   * @author Robert Burrell Donkin 
38   * @since 0.5
39   */
40  public class ObjectStringConverter implements Serializable {
41      
42      /*** Standard name for option giving flavour */
43      public static final String FLAVOUR_OPTION_NAME 
44          = "org.apache.commons.betwixt.flavour";
45      
46      /***
47        * Converts an object to a string representation.
48        * This basic implementation returns object.toString() 
49        * or an empty string if the given object is null.
50        *
51        * @param object the object to be converted, possibly null
52        * @param type the property class of the object, not null
53        * @param flavour a string allow symantic differences in formatting to be communicated
54        * @param context the context, not null
55        * @deprecated 0.7 use {@link #objectToString(Object, Class, Context)} instead. 
56        * The preferred way to support flavours is by setting the
57        * <code>org.apache.commons.betwixt.FLAVOUR</code> option.
58        * This can then be retrieved by calling {@link Context#getOptions()}
59        * @return a String representation, not null
60        */
61      public String objectToString(Object object, Class type, String flavour, Context context) {
62          if ( object != null ) {
63              return object.toString();
64          } 
65          return "";
66      }
67      
68      /***
69        * Converts a string representation to an object.
70        * It is acceptable for an implementation to return the string if it cannot convert 
71        * the string to the given class type.
72        * This basic implementation just returns a string.
73        * 
74        * @param value the String to be converted
75        * @param type the property class to be returned (if possible), not null
76        * @param flavour a string allow symantic differences in formatting to be communicated
77        * @param context the context, not null
78        * @deprecated 0.7 use {@link #stringToObject(String, Class, Context)} instead.
79        * The preferred way to support flavours is by setting the
80        * <code>org.apache.commons.betwixt.FLAVOUR</code> option.
81        * This can then be retrieved by calling {@link Context#getOptions()}
82        * @return an Object converted from the String, not null
83        */
84      public Object stringToObject(String value, Class type, String flavour, Context context) {
85          return value;
86      }
87  
88      
89      /***
90        * Converts an object to a string representation.
91        * This basic implementation returns object.toString() 
92        * or an empty string if the given object is null.
93        *
94        * @since 0.7
95        * @param object the object to be converted, possibly null
96        * @param type the property class of the object, not null
97        * @param context the context, not null
98        * @return a String representation, not null
99        */
100     public String objectToString(Object object, Class type, Context context) {
101         String flavour = getFlavour(context);
102         return objectToString(object, type, flavour, context);
103     }
104     
105     /***
106       * Converts a string representation to an object.
107       * It is acceptable for an implementation to return the string if it cannot convert 
108       * the string to the given class type.
109       * This basic implementation just returns a string.
110       * 
111       * @since 0.7
112       * @param value the String to be converted
113       * @param type the property class to be returned (if possible), not null
114       * @param context the context, not null
115       * @return an Object converted from the String, not null
116       */
117     public Object stringToObject(String value, Class type, Context context) {
118         String flavour = getFlavour(context);
119         return stringToObject(value, type, flavour, context);
120     }
121 
122     /***
123      * Gets the current flavour from the context.
124      * @param context <code>Context</code>, not null
125      */
126     private String getFlavour(Context context) {
127         String flavour = null;
128         Options options = context.getOptions();
129         if (options != null) {
130             flavour = options.getValue(FLAVOUR_OPTION_NAME);
131         }
132         return flavour;
133     }
134 }