KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > lang > TextFormat


1 /*
2  * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3  * Copyright (C) 2005 - Javolution (http://javolution.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */
9 package javolution.lang;
10
11 import j2me.lang.CharSequence;
12 import javolution.realtime.RealtimeObject;
13 import java.io.IOException;
14
15 /**
16  * <p> This class represents the base format for text parsing and formatting;
17  * it supports {@link CharSequence} and {@link javolution.lang.Appendable}
18  * interfaces for greater flexibility.</p>
19  *
20  * <p> Changes to the current format (used by <code>valueOf(CharSequence)</code>,
21  * <code>toString()</code> or <code>toText()</code>)
22  * can be {@link javolution.realtime.LocalContext locally scoped}.
23  * For example: <pre>
24  * public class Foo {
25  * private static final LocalReference&lt;TextFormat&lt;Foo&gt;&gt; TEXT_FORMAT
26  * = new LocalReference&lt;TextFormat&lt;Foo&gt;&gt;(DEFAULT);
27  * public static TextFormat&lt;Foo&gt; getTextFormat() {
28  * return TEXT_FORMAT.get();
29  * }
30  * public static void setTextFormat(TextFormat&lt;Foo&gt; format) {
31  * TEXT_FORMAT.set(format);
32  * }
33  * }
34  * ...
35  * LocalContext.enter();
36  * try {
37  * Foo.setTextFormat(myFormat);
38  * System.out.println(foo); // Current thread displays foo using myFormat.
39  * } finally {
40  * LocalContext.exit(); // Current thread reverts to previous format.
41  * }</pre></p>
42  *
43  * <p> For parsing/formatting of primitive types, the {@link TypeFormat}
44  * utility class is recommended (fast with no intermediate
45  * object creation).</p>
46  *
47  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle </a>
48  * @version 3.3, May 10, 2005
49  */
50 public abstract class TextFormat/*<T>*/ {
51
52     /**
53      * Default constructor.
54      */
55     protected TextFormat() {
56     }
57
58     /**
59      * Formats the specified object to a {@link Text} instance.
60      *
61      * @param obj the object being formated.
62      * @return the text representing the specified object.
63      */
64     public abstract Text format(Object/*T*/ obj);
65
66     /**
67      * Parses a portion of the specified <code>CharSequence</code> from the
68      * specified position to produce an object. If parsing succeeds, then the
69      * index of the <code>pos</code> argument is updated to the index after
70      * the last character used.
71      *
72      * @param csq the <code>CharSequence</code> to parse.
73      * @param pos an object holding the parsing index.
74      * @return an <code>Object</code> parsed from the character sequence.
75      * @throws IllegalArgumentException if the character sequence contains
76      * an illegal syntax.
77      */
78     public abstract Object/*T*/ parse(CharSequence csq, Cursor pos);
79
80     /**
81      * Parses a whole character sequence from the beginning to produce an object
82      * (convenience method). A temporary cursor is allocated from the "stack"
83      * when executing in a {@link javolution.realtime.PoolContext PoolContext}
84      * and {@link Cursor#recycle recycled} to the "stack" after usage.
85      *
86      * @param csq the <code>CharSequence</code> to parse.
87      * @return <code>parse(csq, cursor)</code>
88      * @throws IllegalArgumentException if the character sequence contains an
89      * illegal syntax or if the whole sequence has not been completely
90      * parsed.
91      */
92     public final Object/*T*/ parse(CharSequence csq) {
93         Cursor cursor = Cursor.newInstance();
94         try {
95             Object/*T*/ obj = parse(csq, cursor);
96             if (cursor.getIndex() == csq.length()) {
97                 return obj;
98             } else {
99                 throw new IllegalArgumentException("Parsing of " + csq
100                         + " incomplete (terminated at index: "
101                         + cursor.getIndex() + ")");
102             }
103         } finally {
104             cursor.recycle();
105         }
106     }
107
108     /**
109      * Formats an object into the specified <code>Appendable</code>
110      * (convenience method).
111      *
112      * @param obj the object to format.
113      * @param dest the <code>Appendable</code> destination.
114      * @return the specified <code>Appendable</code>.
115      * @throws IOException if an I/O exception occurs.
116      */
117     public final Appendable format(Object/*T*/ obj, Appendable dest) throws IOException {
118         Text txt = format(obj);
119         return dest.append(txt);
120     }
121     
122     /**
123      * This class represents the parsing cursor. In case of parsing error,
124      * the cursor should be set to the location where the error occured.
125      */
126     public static final class Cursor extends RealtimeObject {
127         
128         /**
129          * Holds the cursor factory.
130          */
131         private static final Factory FACTORY = new Factory() {
132             public Object create() {
133                 return new Cursor();
134             }
135         };
136
137         /**
138          * Holds the cursor index.
139          */
140         private int _index;
141
142         /**
143          * Returns a temporary cursor allocated from the "stack" when executing
144          * in a {@link javolution.realtime.PoolContext PoolContext} and
145          * {@link #recycle recyclable} to the "stack".
146          *
147          * @return a {@link javolution.realtime.ObjectFactory factory} produced
148          * cursor instance.
149          */
150         public static Cursor newInstance() {
151             Cursor cursor = (Cursor) FACTORY.object();
152             cursor._index = 0;
153             return cursor;
154         }
155
156         /**
157          * Returns this cursor index.
158          *
159          * @return the index of the next character to parse.
160          */
161         public int getIndex() {
162             return _index;
163         }
164
165         /**
166          * Sets the cursor index.
167          *
168          * @param i the index of the next character to parse.
169          */
170         public void setIndex(int i) {
171             _index = i;
172         }
173
174         /**
175          * Increments the cursor index by the specified value.
176          *
177          * @param i the increment value.
178          */
179         public void increment(int i) {
180             _index += i;
181         }
182         
183         /**
184          * Recycles this cursor after usage.
185          */
186         public void recycle() {
187             super.recycle();
188         }
189     }
190 }
Popular Tags