Source Code Cross Referenced for Format.java in  » 6.0-JDK-Modules » j2me » java » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules » j2me » java.text 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        /*
002:         * 
003:         * @(#)Format.java	1.35 06/10/10
004:         * 
005:         * Portions Copyright  2000-2006 Sun Microsystems, Inc. All Rights
006:         * Reserved.  Use is subject to license terms.
007:         * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
008:         * 
009:         * This program is free software; you can redistribute it and/or
010:         * modify it under the terms of the GNU General Public License version
011:         * 2 only, as published by the Free Software Foundation.
012:         * 
013:         * This program is distributed in the hope that it will be useful, but
014:         * WITHOUT ANY WARRANTY; without even the implied warranty of
015:         * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016:         * General Public License version 2 for more details (a copy is
017:         * included at /legal/license.txt).
018:         * 
019:         * You should have received a copy of the GNU General Public License
020:         * version 2 along with this work; if not, write to the Free Software
021:         * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022:         * 02110-1301 USA
023:         * 
024:         * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
025:         * Clara, CA 95054 or visit www.sun.com if you need additional
026:         * information or have any questions.
027:         */
028:
029:        /*
030:         * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
031:         * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved
032:         *
033:         *   The original version of this source code and documentation is copyrighted
034:         * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
035:         * materials are provided under terms of a License Agreement between Taligent
036:         * and Sun. This technology is protected by multiple US and International
037:         * patents. This notice and attribution to Taligent may not be removed.
038:         *   Taligent is a registered trademark of Taligent, Inc.
039:         *
040:         */
041:
042:        package java.text;
043:
044:        import java.io.Serializable;
045:
046:        /**
047:         * <code>Format</code> is an abstract base class for formatting locale-sensitive
048:         * information such as dates, messages, and numbers.
049:         *
050:         * <p>
051:         * <code>Format</code> defines the programming interface for formatting
052:         * locale-sensitive objects into <code>String</code>s (the
053:         * <code>format</code> method) and for parsing <code>String</code>s back
054:         * into objects (the <code>parseObject</code> method).
055:         *
056:         * <p>
057:         * Generally, a format's <code>parseObject</code> method must be able to parse
058:         * any string formatted by its <code>format</code> method. However, there may 
059:         * be exceptional cases where this is not possible. For example, a
060:         * <code>format</code> method might create two adjacent integer numbers with
061:         * no separator in between, and in this case the <code>parseObject</code> could
062:         * not tell which digits belong to which number.
063:         *
064:         * <h4>Subclassing</h4>
065:         *
066:         * <p>
067:         * The Java 2 platform provides three specialized subclasses of <code>Format</code>--
068:         * <code>DateFormat</code>, <code>MessageFormat</code>, and
069:         * <code>NumberFormat</code>--for formatting dates, messages, and numbers,
070:         * respectively.
071:         * <p>
072:         * Concrete subclasses must implement three methods:
073:         * <ol>
074:         * <li> <code>format(Object obj, StringBuffer toAppendTo, FieldPosition pos)</code>
075:         * <li> <code>formatToCharacterIterator(Object obj)</code>
076:         * <li> <code>parseObject(String source, ParsePosition pos)</code>
077:         * </ol>
078:         * These general methods allow polymorphic parsing and formatting of objects
079:         * and are used, for example, by <code>MessageFormat</code>.
080:         * Subclasses often also provide additional <code>format</code> methods for
081:         * specific input types as well as <code>parse</code> methods for specific
082:         * result types. Any <code>parse</code> method that does not take a
083:         * <code>ParsePosition</code> argument should throw <code>ParseException</code>
084:         * when no text in the required format is at the beginning of the input text.
085:         *
086:         * <p>
087:         * Most subclasses will also implement the following factory methods:
088:         * <ol>
089:         * <li>
090:         * <code>getInstance</code> for getting a useful format object appropriate
091:         * for the current locale
092:         * <li>
093:         * <code>getInstance(Locale)</code> for getting a useful format
094:         * object appropriate for the specified locale
095:         * </ol>
096:         * In addition, some subclasses may also implement other
097:         * <code>getXxxxInstance</code> methods for more specialized control. For
098:         * example, the <code>NumberFormat</code> class provides
099:         * <code>getPercentInstance</code> and <code>getCurrencyInstance</code>
100:         * methods for getting specialized number formatters.
101:         *
102:         * <p>
103:         * Subclasses of <code>Format</code> that allow programmers to create objects
104:         * for locales (with <code>getInstance(Locale)</code> for example)
105:         * must also implement the following class method:
106:         * <blockquote>
107:         * <pre>
108:         * public static Locale[] getAvailableLocales()
109:         * </pre>
110:         * </blockquote>
111:         *
112:         * <p>
113:         * And finally subclasses may define a set of constants to identify the various
114:         * fields in the formatted output. These constants are used to create a FieldPosition
115:         * object which identifies what information is contained in the field and its
116:         * position in the formatted result. These constants should be named
117:         * <code><em>item</em>_FIELD</code> where <code><em>item</em></code> identifies
118:         * the field. For examples of these constants, see <code>ERA_FIELD</code> and its
119:         * friends in {@link DateFormat}.
120:         *
121:         * <h4><a name="synchronization">Synchronization</a></h4>
122:         *
123:         * <p>
124:         * Formats are generally not synchronized.
125:         * It is recommended to create separate format instances for each thread.
126:         * If multiple threads access a format concurrently, it must be synchronized
127:         * externally.
128:         *
129:         * @see          java.text.ParsePosition
130:         * @see          java.text.FieldPosition
131:         * @see          java.text.NumberFormat
132:         * @see          java.text.DateFormat
133:         * @see          java.text.MessageFormat
134:         * @version      1.28, 01/19/00
135:         * @author       Mark Davis
136:         */
137:        public abstract class Format implements  Serializable, Cloneable {
138:
139:            private static final long serialVersionUID = -299282585814624189L;
140:
141:            /**
142:             * Formats an object to produce a string. This is equivalent to
143:             * <blockquote>
144:             * {@link #format(Object, StringBuffer, FieldPosition) format}<code>(obj,
145:             *         new StringBuffer(), new FieldPosition(0)).toString();</code>
146:             * </blockquote>
147:             *
148:             * @param obj    The object to format
149:             * @return       Formatted string.
150:             * @exception IllegalArgumentException if the Format cannot format the given
151:             *            object
152:             */
153:            public final String format(Object obj) {
154:                return format(obj, new StringBuffer(), new FieldPosition(0))
155:                        .toString();
156:            }
157:
158:            /**
159:             * Formats an object and appends the resulting text to a given string
160:             * buffer.
161:             * If the <code>pos</code> argument identifies a field used by the format,
162:             * then its indices are set to the beginning and end of the first such
163:             * field encountered.
164:             *
165:             * @param obj    The object to format
166:             * @param toAppendTo    where the text is to be appended
167:             * @param pos    A <code>FieldPosition</code> identifying a field
168:             *               in the formatted text
169:             * @return       the string buffer passed in as <code>toAppendTo</code>,
170:             *               with formatted text appended
171:             * @exception NullPointerException if <code>toAppendTo</code> or
172:             *            <code>pos</code> is null
173:             * @exception IllegalArgumentException if the Format cannot format the given
174:             *            object
175:             */
176:            public abstract StringBuffer format(Object obj,
177:                    StringBuffer toAppendTo, FieldPosition pos);
178:
179:            /**
180:             * Formats an Object producing an <code>AttributedCharacterIterator</code>.
181:             * You can use the returned <code>AttributedCharacterIterator</code>
182:             * to build the resulting String, as well as to determine information
183:             * about the resulting String.
184:             * <p>
185:             * Each attribute key of the AttributedCharacterIterator will be of type
186:             * <code>Field</code>. It is up to each <code>Format</code> implementation
187:             * to define what the legal values are for each attribute in the
188:             * <code>AttributedCharacterIterator</code>, but typically the attribute
189:             * key is also used as the attribute value.
190:             * <p>The default implementation creates an
191:             * <code>AttributedCharacterIterator</code> with no attributes. Subclasses
192:             * that support fields should override this and create an
193:             * <code>AttributedCharacterIterator</code> with meaningful attributes.
194:             *
195:             * @exception NullPointerException if obj is null.
196:             * @exception IllegalArgumentException when the Format cannot format the
197:             *            given object.
198:             * @param obj The object to format
199:             * @return AttributedCharacterIterator describing the formatted value.
200:             * @since 1.4
201:             */
202:            public AttributedCharacterIterator formatToCharacterIterator(
203:                    Object obj) {
204:                return createAttributedCharacterIterator(format(obj));
205:            }
206:
207:            /**
208:             * Parses text from a string to produce an object.
209:             * <p>
210:             * The method attempts to parse text starting at the index given by
211:             * <code>pos</code>.
212:             * If parsing succeeds, then the index of <code>pos</code> is updated
213:             * to the index after the last character used (parsing does not necessarily
214:             * use all characters up to the end of the string), and the parsed
215:             * object is returned. The updated <code>pos</code> can be used to
216:             * indicate the starting point for the next call to this method.
217:             * If an error occurs, then the index of <code>pos</code> is not
218:             * changed, the error index of <code>pos</code> is set to the index of
219:             * the character where the error occurred, and null is returned.
220:             *
221:             * @param source A <code>String</code>, part of which should be parsed.
222:             * @param pos A <code>ParsePosition</code> object with index and error
223:             *            index information as described above.
224:             * @return An <code>Object</code> parsed from the string. In case of
225:             *         error, returns null.
226:             * @exception NullPointerException if <code>pos</code> is null.
227:             */
228:            public abstract Object parseObject(String source, ParsePosition pos);
229:
230:            /**
231:             * Parses text from the beginning of the given string to produce an object.
232:             * The method may not use the entire text of the given string.
233:             *
234:             * @param source A <code>String</code> whose beginning should be parsed.
235:             * @return An <code>Object</code> parsed from the string.
236:             * @exception ParseException if the beginning of the specified string
237:             *            cannot be parsed.
238:             */
239:            public Object parseObject(String source) throws ParseException {
240:                ParsePosition pos = new ParsePosition(0);
241:                Object result = parseObject(source, pos);
242:                if (pos.index == 0) {
243:                    throw new ParseException(
244:                            "Format.parseObject(String) failed", pos.errorIndex);
245:                }
246:                return result;
247:            }
248:
249:            /**
250:             * Creates and returns a copy of this object.
251:             *
252:             * @return a clone of this instance.
253:             */
254:            public Object clone() {
255:                try {
256:                    return super .clone();
257:                } catch (CloneNotSupportedException e) {
258:                    // will never happen
259:                    return null;
260:                }
261:            }
262:
263:            //
264:            // Convenience methods for creating AttributedCharacterIterators from
265:            // different parameters.
266:            // 
267:
268:            /**
269:             * Creates an <code>AttributedCharacterIterator</code> for the String
270:             * <code>s</code>.
271:             *
272:             * @param s String to create AttributedCharacterIterator from
273:             * @return AttributedCharacterIterator wrapping s
274:             */
275:            AttributedCharacterIterator createAttributedCharacterIterator(
276:                    String s) {
277:                AttributedString as = new AttributedString(s);
278:
279:                return as.getIterator();
280:            }
281:
282:            /**
283:             * Creates an <code>AttributedCharacterIterator</code> containg the
284:             * concatenated contents of the passed in
285:             * <code>AttributedCharacterIterator</code>s.
286:             *
287:             * @param iterators AttributedCharacterIterators used to create resulting
288:             *                  AttributedCharacterIterators
289:             * @return AttributedCharacterIterator wrapping passed in
290:             *         AttributedCharacterIterators
291:             */
292:            AttributedCharacterIterator createAttributedCharacterIterator(
293:                    AttributedCharacterIterator[] iterators) {
294:                AttributedString as = new AttributedString(iterators);
295:
296:                return as.getIterator();
297:            }
298:
299:            /**
300:             * Returns an AttributedCharacterIterator with the String
301:             * <code>string</code> and additional key/value pair <code>key</code>,
302:             * <code>value</code>.
303:             *
304:             * @param string String to create AttributedCharacterIterator from
305:             * @param key Key for AttributedCharacterIterator
306:             * @param value Value associated with key in AttributedCharacterIterator
307:             * @return AttributedCharacterIterator wrapping args
308:             */
309:            AttributedCharacterIterator createAttributedCharacterIterator(
310:                    String string, AttributedCharacterIterator.Attribute key,
311:                    Object value) {
312:                AttributedString as = new AttributedString(string);
313:
314:                as.addAttribute(key, value);
315:                return as.getIterator();
316:            }
317:
318:            /**
319:             * Creates an AttributedCharacterIterator with the contents of
320:             * <code>iterator</code> and the additional attribute <code>key</code>
321:             * <code>value</code>.
322:             *
323:             * @param iterator Initial AttributedCharacterIterator to add arg to
324:             * @param key Key for AttributedCharacterIterator
325:             * @param value Value associated with key in AttributedCharacterIterator
326:             * @return AttributedCharacterIterator wrapping args
327:             */
328:            AttributedCharacterIterator createAttributedCharacterIterator(
329:                    AttributedCharacterIterator iterator,
330:                    AttributedCharacterIterator.Attribute key, Object value) {
331:                AttributedString as = new AttributedString(iterator);
332:
333:                as.addAttribute(key, value);
334:                return as.getIterator();
335:            }
336:
337:            /**
338:             * Defines constants that are used as attribute keys in the
339:             * <code>AttributedCharacterIterator</code> returned
340:             * from <code>Format.formatToCharacterIterator</code> and as
341:             * field identifiers in <code>FieldPosition</code>.
342:             *
343:             * @since 1.4
344:             */
345:            public static class Field extends
346:                    AttributedCharacterIterator.Attribute {
347:                /**
348:                 * Creates a Field with the specified name.
349:                 *
350:                 * @param name Name of the attribute
351:                 */
352:                protected Field(String name) {
353:                    super (name);
354:                }
355:            }
356:
357:            /**
358:             * FieldDelegate is notified by the various <code>Format</code>
359:             * implementations as they are formatting the Objects. This allows for
360:             * storage of the individual sections of the formatted String for
361:             * later use, such as in a <code>FieldPosition</code> or for an
362:             * <code>AttributedCharacterIterator</code>.
363:             * <p>
364:             * Delegates should NOT assume that the <code>Format</code> will notify
365:             * the delegate of fields in any particular order.
366:             *
367:             * @see FieldPosition.Delegate
368:             * @see CharacterIteratorFieldDelegate
369:             */
370:            interface FieldDelegate {
371:                /**
372:                 * Notified when a particular region of the String is formatted. This
373:                 * method will be invoked if there is no corresponding integer field id
374:                 * matching <code>attr</code>.
375:                 *
376:                 * @param attr Identifies the field matched
377:                 * @param value Value associated with the field
378:                 * @param start Beginning location of the field, will be >= 0
379:                 * @param end End of the field, will be >= start and <= buffer.length()
380:                 * @param buffer Contains current formatted value, receiver should
381:                 *        NOT modify it.
382:                 */
383:                public void formatted(Format.Field attr, Object value,
384:                        int start, int end, StringBuffer buffer);
385:
386:                /**
387:                 * Notified when a particular region of the String is formatted.
388:                 *
389:                 * @param fieldID Identifies the field by integer
390:                 * @param attr Identifies the field matched
391:                 * @param value Value associated with the field
392:                 * @param start Beginning location of the field, will be >= 0
393:                 * @param end End of the field, will be >= start and <= buffer.length()
394:                 * @param buffer Contains current formatted value, receiver should
395:                 *        NOT modify it.
396:                 */
397:                public void formatted(int fieldID, Format.Field attr,
398:                        Object value, int start, int end, StringBuffer buffer);
399:            }
400:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.