001: /* ====================================================================
002: * Tea - Copyright (c) 1997-2000 Walt Disney Internet Group
003: * ====================================================================
004: * The Tea Software License, Version 1.1
005: *
006: * Copyright (c) 2000 Walt Disney Internet Group. All rights reserved.
007: *
008: * Redistribution and use in source and binary forms, with or without
009: * modification, are permitted provided that the following conditions
010: * are met:
011: *
012: * 1. Redistributions of source code must retain the above copyright
013: * notice, this list of conditions and the following disclaimer.
014: *
015: * 2. Redistributions in binary form must reproduce the above copyright
016: * notice, this list of conditions and the following disclaimer in
017: * the documentation and/or other materials provided with the
018: * distribution.
019: *
020: * 3. The end-user documentation included with the redistribution,
021: * if any, must include the following acknowledgment:
022: * "This product includes software developed by the
023: * Walt Disney Internet Group (http://opensource.go.com/)."
024: * Alternately, this acknowledgment may appear in the software itself,
025: * if and wherever such third-party acknowledgments normally appear.
026: *
027: * 4. The names "Tea", "TeaServlet", "Kettle", "Trove" and "BeanDoc" must
028: * not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact opensource@dig.com.
031: *
032: * 5. Products derived from this software may not be called "Tea",
033: * "TeaServlet", "Kettle" or "Trove", nor may "Tea", "TeaServlet",
034: * "Kettle", "Trove" or "BeanDoc" appear in their name, without prior
035: * written permission of the Walt Disney Internet Group.
036: *
037: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
038: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
039: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
040: * DISCLAIMED. IN NO EVENT SHALL THE WALT DISNEY INTERNET GROUP OR ITS
041: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
042: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
043: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
044: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
045: * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
046: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
047: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
048: * ====================================================================
049: *
050: * For more information about Tea, please see http://opensource.go.com/.
051: */
052:
053: package com.go.tea.runtime;
054:
055: /******************************************************************************
056: * Interface establishes basic printing and formatting functions for a template
057: * runtime context.
058: *
059: * @see com.go.tea.compiler.Compiler#getRuntimeContext
060: * @author Brian S O'Neill
061: * @version
062: * <!--$$Revision:--> 41 <!-- $-->, <!--$$JustDate:--> 01/04/19 <!-- $-->
063: * @see DefaultContext
064: */
065: public interface Context extends OutputReceiver {
066:
067: /**
068: * Method that is the runtime receiver. Implementations should call one
069: * of the toString methods when converting this object to a string.
070: * <p>
071: * NOTE: This method should <b>not</b> be called directly within a
072: * template.
073: *
074: * @see com.go.tea.compiler.Compiler#getRuntimeReceiver
075: * @hidden
076: */
077: public void print(Object obj) throws Exception;
078:
079: /**
080: * @hidden
081: */
082: public void print(java.util.Date date) throws Exception;
083:
084: /**
085: * @hidden
086: */
087: public void print(Number n) throws Exception;
088:
089: /**
090: * @hidden
091: */
092: public void print(int n) throws Exception;
093:
094: /**
095: * @hidden
096: */
097: public void print(float n) throws Exception;
098:
099: /**
100: * @hidden
101: */
102: public void print(long n) throws Exception;
103:
104: /**
105: * @hidden
106: */
107: public void print(double n) throws Exception;
108:
109: /**
110: * A function that converts an object to a string, applying any applicable
111: * formatting settings. The returned String is never null.
112: *
113: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
114: * @hidden
115: */
116: public String toString(Object obj);
117:
118: /**
119: * A function that converts a string to the null format string if it is
120: * null. Otherwise, it is returned unchanged.
121: *
122: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
123: * @hidden
124: */
125: public String toString(String str);
126:
127: /**
128: * A function that converts a date to a string, using the current
129: * date format.
130: *
131: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
132: * @hidden
133: */
134: public String toString(java.util.Date date);
135:
136: /**
137: * A function that converts a number to a string, using the current
138: * number format.
139: *
140: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
141: * @hidden
142: */
143: public String toString(Number n);
144:
145: /**
146: * A function that converts a number to a string, using the current
147: * number format.
148: *
149: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
150: * @hidden
151: */
152: public String toString(int n);
153:
154: /**
155: * A function that converts a number to a string, using the current
156: * number format.
157: *
158: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
159: * @hidden
160: */
161: public String toString(float n);
162:
163: /**
164: * A function that converts a number to a string, using the current
165: * number format.
166: *
167: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
168: * @hidden
169: */
170: public String toString(long n);
171:
172: /**
173: * A function that converts a number to a string, using the current
174: * number format.
175: *
176: * @see com.go.tea.compiler.Compiler#getRuntimeStringConverter
177: * @hidden
178: */
179: public String toString(double n);
180:
181: /**
182: * Setting the locale resets date and number formats to the default for
183: * that locale. Setting a locale of null resets date and number formats
184: * to the system defaults.
185: * <p>
186: * See getAvailableLocales to get all the available language, country
187: * and variant codes.
188: *
189: * @param locale pre-constructed locale object
190: */
191: public void setLocale(java.util.Locale locale);
192:
193: /**
194: * Setting the locale resets date and number formats to the default for
195: * that locale.
196: *
197: * @param language language code
198: * @param country country code
199: */
200: public void setLocale(String language, String country);
201:
202: /**
203: * Setting the locale resets date and number formats to the default for
204: * that locale.
205: *
206: * @param language language code
207: * @param country country code
208: * @param variant optional variant code
209: */
210: public void setLocale(String language, String country,
211: String variant);
212:
213: /**
214: * Returns the current locale setting.
215: */
216: public java.util.Locale getLocale();
217:
218: /**
219: * Returns a list of all the available locales.
220: */
221: public java.util.Locale[] getAvailableLocales();
222:
223: /**
224: * A function that sets the formatted value of null object references.
225: *
226: * @param format string to print in place of "null".
227: */
228: public void nullFormat(String format);
229:
230: /**
231: * Returns the current null format specification.
232: */
233: public String getNullFormat();
234:
235: /**
236: * Defines a format to use when printing dates from templates.
237: * Passing null sets the format back to the default.
238: * <p>
239: * <strong>Time Format Syntax:</strong>
240: * <p>
241: * To specify the time format use a <em>time pattern</em> string.
242: * In this pattern, all ASCII letters are reserved as pattern letters,
243: * which are defined as the following:
244: *
245: * <blockquote>
246: * <pre>
247: * Symbol Meaning Presentation Example
248: * ------ ------- ------------ -------
249: * G era designator (Text) AD
250: * y year (Number) 1996
251: * M month in year (Text & Number) July & 07
252: * d day in month (Number) 10
253: * h hour in am/pm (1~12) (Number) 12
254: * H hour in day (0~23) (Number) 0
255: * m minute in hour (Number) 30
256: * s second in minute (Number) 55
257: * S millisecond (Number) 978
258: * E day in week (Text) Tuesday
259: * D day in year (Number) 189
260: * F day of week in month (Number) 2 (2nd Wed in July)
261: * w week in year (Number) 27
262: * W week in month (Number) 2
263: * a am/pm marker (Text) PM
264: * k hour in day (1~24) (Number) 24
265: * K hour in am/pm (0~11) (Number) 0
266: * z time zone (Text) Pacific Standard Time
267: * ' escape for text (Delimiter)
268: * '' single quote (Literal) '
269: * </pre>
270: * </blockquote>
271: * The count of pattern letters determine the format.
272: * <p>
273: * <strong>(Text)</strong>: 4 or more pattern letters--use full form,
274: * less than 4--use short or abbreviated form if one exists.
275: * <p>
276: * <strong>(Number)</strong>: the minimum number of digits. Shorter
277: * numbers are zero-padded to this amount. Year is handled specially;
278: * that is, if the count of 'y' is 2, the Year will be truncated to 2
279: * digits.
280: * <p>
281: * <strong>(Text & Number)</strong>: 3 or over, use text, otherwise use
282: * number.
283: * <p>
284: * Any characters in the pattern that are not in the ranges of
285: * ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance,
286: * characters like ':', '.', ' ', '#' and '@' will appear in the resulting
287: * time text even they are not embraced within single quotes.
288: * <p>
289: * A pattern containing any invalid pattern letter will result in a thrown
290: * exception during formatting or parsing.
291: * <p>
292: * <strong>Examples:</strong>
293: * <blockquote>
294: * <pre>
295: * Format Pattern Result
296: * -------------- -------
297: * "yyyy.MM.dd G 'at' hh:mm:ss z" ->> 1996.07.10 AD at 15:08:56 PDT
298: * "EEE, MMM d, ''yy" ->> Wed, July 10, '96
299: * "h:mm a" ->> 12:08 PM
300: * "hh 'o''clock' a, zzzz" ->> 12 o'clock PM, Pacific Daylight Time
301: * "K:mm a, z" ->> 0:00 PM, PST
302: * "yyyyy.MMMMM.dd GGG hh:mm aaa" ->> 1996.July.10 AD 12:08 PM
303: * </pre>
304: * </blockquote>
305: *
306: * @param format date format specification string
307: */
308: public void dateFormat(String format);
309:
310: /**
311: * A function that sets the formatted value of dates.
312: *
313: * @param format date format specification string
314: * @param timeZoneID time zone ID, i.e. "PST"
315: */
316: public void dateFormat(String format, String timeZoneID);
317:
318: /**
319: * Returns the current date format specification.
320: */
321: public String getDateFormat();
322:
323: /**
324: * Returns the current date format time zone.
325: */
326: public String getDateFormatTimeZone();
327:
328: /**
329: * Returns a list of all the available time zones.
330: */
331: public java.util.TimeZone[] getAvailableTimeZones();
332:
333: /**
334: * A function that sets the formatted value of numbers.
335: *
336: * Defines a format to use when printing numbers from templates.
337: * Passing null sets the format back to the default. The format string is
338: * of the form "#.#".
339: * <p>
340: * Here are the special characters used in the parts of the format string,
341: * with notes on their usage.
342: * <pre>
343: * Symbol Meaning
344: * ------ -------
345: * 0 a digit
346: * # a digit, zero shows as absent
347: * . placeholder for decimal separator.
348: * , placeholder for grouping separator.
349: * ; separates formats.
350: * - default negative prefix.
351: * % multiply by 100 and show as percentage
352: * ? multiply by 1000 and show as per mille
353: * \u00a4 currency sign; replaced by currency symbol;
354: * if doubled, replaced by international currency
355: * symbol. If present in a pattern, the monetary
356: * decimal separator is used instead of the decimal
357: * separator. (Unicode escape is \\u00a4)
358: * X any other characters can be used in the prefix or suffix
359: * ' used to quote special characters in a prefix or suffix.
360: * </pre>
361: *
362: * @param format number format specification string
363: */
364: public void numberFormat(String format);
365:
366: /**
367: * A function that sets the formatted value of numbers.
368: *
369: * Defines a format to use when printing numbers from templates.
370: * Passing null sets the format back to the default. The format string is
371: * of the form "#.#".
372: * <p>
373: * Here are the special characters used in the parts of the format string,
374: * with notes on their usage.
375: * <pre>
376: * Symbol Meaning
377: * ------ -------
378: * 0 a digit
379: * # a digit, zero shows as absent
380: * . placeholder for decimal separator.
381: * , placeholder for grouping separator.
382: * ; separates formats.
383: * - default negative prefix.
384: * % multiply by 100 and show as percentage
385: * ? multiply by 1000 and show as per mille
386: * \u00a4 currency sign; replaced by currency symbol;
387: * if doubled, replaced by international currency
388: * symbol. If present in a pattern, the monetary
389: * decimal separator is used instead of the decimal
390: * separator. (Unicode escape is \\u00a4)
391: * X any other characters can be used in the prefix or suffix
392: * ' used to quote special characters in a prefix or suffix.
393: * </pre>
394: *
395: * @param format number format specification string
396: * @param infinity display string for infinity
397: * @param NaN display string for not-a-number, resulting from zero divided
398: * by zero.
399: */
400: public void numberFormat(String format, String infinity, String NaN);
401:
402: /**
403: * Returns the current number format specification.
404: */
405: public String getNumberFormat();
406:
407: /**
408: * Returns the current number format for infinity.
409: */
410: public String getNumberFormatInfinity();
411:
412: /**
413: * Returns the current number format for NaN.
414: */
415: public String getNumberFormatNaN();
416: }
|