sun.com/docs/books/tutorial/uiswing/concurrency/index.html">Swing tutorial for details.

The base class for all object formats. Formats are used to define the stored layout for all persistent classes, including simple types. The design documentation below describes the storage format for entities and its relationship to information stored per format in the catalog. Requirements ------------ + Provides EntityBinding for objects and EntryBinding for keys. + Provides SecondaryKeyCreator, SecondaryMultiKeyCreator and SecondaryMultiKeyNullifier (SecondaryKeyNullifier is redundant). + Works with reflection and bytecode enhancement. + For reflection only, works with any entity model not just annotations. + Bindings are usable independently of the persist API. + Performance is almost equivalent to hand coded tuple bindings. + Small performance penalty for compatible class changes (new fields, widening). + Secondary key create/nullify do not have to deserialize the entire record; in other words, store secondary keys at the start of the data. Class Format ------------ Every distinct class format is given a unique format ID. Class IDs are not equivalent to class version numbers (as in the version property of @Entity and @Persistent) because the format can change when the version number does not. Changes that cause a unique format ID to be assigned are: + Add field. + Widen field type. + Change primitive type to primitive wrapper class. + Add or drop secondary key. + Any incompatible class change. The last item, incompatible class changes, also correspond to a class version change. For each distinct class format the following information is conceptually stored in the catalog, keyed by format ID. - Class name - Class version number - Superclass format - Kind: simple, enum, complex, array - For kind == simple: - Primitive class - For kind == enum: - Array of constant names, sorted by name. - For kind == complex: - Primary key fieldInfo, or null if no primary key is declared - Array of secondary key fieldInfo, sorted by field name - Array of other fieldInfo, sorted by field name - For kind == array: - Component class format - Number of array dimensions - Other metadata for RawType Where fieldInfo is: - Field name - Field class - Other metadata for RawField Data Layout ----------- For each entity instance the data layout is as follows: instanceData: formatId keyFields... nonKeyFields... keyFields: fieldValue... nonKeyFields: fieldValue... The formatId is the (positive non-zero) ID of a class format, defined above. This is ID of the most derived class of the instance. It is stored as a packed integer. Following the format ID, zero or more sets of secondary key field values appear, followed by zero or more sets of other class field values. The keyFields are the sets of secondary key fields for each class in order of the highest superclass first. Within a class, fields are ordered by field name. The nonKeyFields are the sets of other non-key fields for each class in order of the highest superclass first. Within a class, fields are ordered by field name. A field value is: fieldValue: primitiveValue | nullId | instanceRef | instanceData | simpleValue | enumValue | arrayValue For a primitive type, a primitive value is used as defined for tuple bindings. For float and double, sorted float and sorted double tuple values are used. For a non-primitive type with a null value, a nullId is used that has a zero (illegal formatId) value. This includes String and other simple reference types. The formatId is stored as a packed integer, meaning that it is stored as a single zero byte. For a non-primitive type, an instanceRef is used for a non-null instance that appears earlier in the data byte array. An instanceRef is the negation of the byte offset of the instanceData that appears earlier. It is stored as a packed integer. The remaining rules apply only to reference types with non-null values that do not appear earlier in the data array. For an array type, an array formatId is used that identifies the component type and the number of array dimensions. This is followed by an array length (stored as a packed integer) and zero or more fieldValue elements. For an array with N+1 dimensions where N is greater than zero, the leftmost dimension is enumerated such that each fieldValue element is itself an array of N dimensions or null. arrayValue: formatId length fieldValue... For an enum type, an enumValue is used, consisting of a formatId that identifies the enum class and an enumIndex (stored as a packed integer) that identifies the constant name in the enum constant array of the enum class format: enumValue: formatId enumIndex For a simple type, a simpleValue is used. This consists of the formatId that identifies the class followed by the simple type value. For a primitive wrapper type the simple type value is the corresponding primitive, for a Date it is the milliseconds as a long primitive, and for BigInteger or BigDecimal it is a byte array as defined for tuple bindings of these types. simpleValue: formatId value For all other complex types, an instanceData is used, which is defined above. Secondary Keys -------------- For secondary key support we must account for writing and nullifying specific keys. Rather than instantiating the entity and then performing the secondary key operation, we strive to perform the secondary key operation directly on the byte format. To create a secondary key we skip over other fields and then copy the bytes of the embedded key. This approach is very efficient because a) the entity is not instantiated, and b) the secondary keys are stored at the beginning of the byte format and can be quickly read. To nullify we currently instantiate the raw entity, set the key field to null (or remove it from the array/collection), and convert the raw entity back to bytes. Although the performance of this approach is not ideal because it requires serialization, it avoids the complexity of modifying the packed serialized format directly, adjusting references to key objects, etc. Plus, when we nullify a key we are going to write the record, so the serialization overhead may not be significant. For the record, I tried implementing nullification of the bytes directly and found it was much too complex. Lifecycle --------- Format are managed by a Catalog class. Simple formats are managed by SimpleCatalog, and are copied from the SimpleCatalog by PersistCatalog. Other formats are managed by PersistCatalog. The lifecycle of a format instance is: - Constructed by the catalog when a format is requested for a Class that currently has no associated format. - The catalog calls setId() and adds the format to its format list (indexed by format id) and map (keyed by class name). - The catalog calls collectRelatedFormats(), where a format can create additional formats that it needs, or that should also be persistent. - The catalog calls initializeIfNeeded(), which calls the initialize() method of the format class. - initialize() should initialize any transient fields in the format. initialize() can assume that all related formats are available in the catalog. It may call initializeIfNeeded() for those related formats, if it needs to interact with an initialized related format; this does not cause a cycle, because initializeIfNeeded() does nothing for an already initialized format. - The catalog creates a group of related formats at one time, and then writes its entire list of formats to the catalog DB as a single record. This grouping reduces the number of writes. - When a catalog is opened and the list of existing formats is read. After a format is deserialized, its initializeIfNeeded() method is called. setId() and collectRelatedFormats() are not called, since the ID and related formats are stored in serialized fields. - There are two modes for opening an existing catalog: raw mode and normal mode. In raw mode, the old format is used regardless of whether it matches the current class definition; in fact the class is not accessed and does not need to be present. - In normal mode, for each existing format that is initialized, a new format is also created based on the current class and metadata definition. If the two formats are equal, the new format is discarded. If they are unequal, the new format becomes the current format and the old format's evolve() method is called. evolve() is responsible for adjusting the old format for class evolution. Any number of non-current formats may exist for a given class, and are setup to evolve the single current format for the class. @author Mark Hayes

Describes the format of a document.

Represents a fresnel:Format. @author ryanlee

This is the Planets 'Preservation Object' 'Format' description entity. It is based on the DROID FileFormat entity, but simplified. Other format registries could be supported too.

Note that DROID also provides: 'has priority over' (good for doing PP) and 'signatures' (good for doing PC) but as this is meant to be a simple, interoperable type identifier system, this extra information (which is more oriented to specific use contexts) is not included here.

Types are identified by URIs. As we are currently based on PRONOM, these URIs will be PRONOM info:pronom/fmt/XX URIs. By using these URIs, we retain the ability to add further registries in the future without changing any of this code. @author Andy Jackson @author Fabian Steeg

A class for formatting numbers that follows printf conventions. Also implements C-like atoi and atof functions @deprecated -2001.04.11- eventually to be replaced by java.text.NumberFormat - EMM @author Cay Horstmann Formats the number following printf conventions. Main limitation: Can only handle one format parameter at a time Use multiple Format objects to format more than one number @param s the format string following printf conventionsThe string has a prefix, a format code and a suffix. The prefix and suffix become part of the formatted output. The format code directs the formatting of the (single) parameter to be formatted. The code has the following structure

• a % (required)
• a modifier (optional)

  +

  forces display of + for positive numbers

  0

  show leading zeroes

  -

  align left in the field

  space

  prepend a space in front of positive numbers

  #

  use "alternate" format. Add 0 or 0x for octal or hexadecimal numbers. Don't suppress trailing zeroes in general floating point format.

• an integer denoting field width (optional)
• a period followed by an integer denoting precision (optional)
• a format descriptor (required)

  f

  floating point number in fixed format

  e, E

  floating point number in exponential notation (scientific format). The E format results in an uppercase E for the exponent (1.14130E+003), the e format in a lowercase e.

  g, G

  floating point number in general format (fixed format for small numbers, exponential format for large numbers). Trailing zeroes are suppressed. The G format results in an uppercase E for the exponent (if any), the g format in a lowercase e.

  d, i

  integer in decimal

  x

  integer in hexadecimal

  o

  integer in octal

  s

  string

  c

  character

@exception IllegalArgumentException if bad format

Format is an abstract base class for formatting locale-sensitive information such as dates, messages, and numbers.

Format defines the programming interface for formatting locale-sensitive objects into Strings (the format method) and for parsing Strings back into objects (the parseObject method).

Generally, a format's parseObject method must be able to parse any string formatted by its format method. However, there may be exceptional cases where this is not possible. For example, a format method might create two adjacent integer numbers with no separator in between, and in this case the parseObject could not tell which digits belong to which number.

Subclassing

The Java Platform provides three specialized subclasses of Format-- DateFormat, MessageFormat, and NumberFormat--for formatting dates, messages, and numbers, respectively.

Concrete subclasses must implement three methods:

1. format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
2. formatToCharacterIterator(Object obj)
3. parseObject(String source, ParsePosition pos)

These general methods allow polymorphic parsing and formatting of objects and are used, for example, by MessageFormat. Subclasses often also provide additional format methods for specific input types as well as parse methods for specific result types. Any parse method that does not take a ParsePosition argument should throw ParseException when no text in the required format is at the beginning of the input text.

Most subclasses will also implement the following factory methods:

1. getInstance for getting a useful format object appropriate for the current locale
2. getInstance(Locale) for getting a useful format object appropriate for the specified locale

In addition, some subclasses may also implement other getXxxxInstance methods for more specialized control. For example, the NumberFormat class provides getPercentInstance and getCurrencyInstance methods for getting specialized number formatters.

Subclasses of Format that allow programmers to create objects for locales (with getInstance(Locale) for example) must also implement the following class method:

 public static Locale[] getAvailableLocales() 

And finally subclasses may define a set of constants to identify the various fields in the formatted output. These constants are used to create a FieldPosition object which identifies what information is contained in the field and its position in the formatted result. These constants should be named item_FIELD where item identifies the field. For examples of these constants, see ERA_FIELD and its friends in {@link DateFormat}.

Synchronization

Formats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally. @see java.text.ParsePosition @see java.text.FieldPosition @see java.text.NumberFormat @see java.text.DateFormat @see java.text.MessageFormat @version 1.37, 12/03/05 @author Mark Davis

sun.com/products/java-media/jmf/2.1.1/apidocs/javax/media/Format.html" target="_blank">this class in the JMF Javadoc. Coding complete. @author Ken Larson

A format describes how to display a field. It specifies font family name, size, attributes (bold, italic, underline, wrap), alignment, and print format.

If a field's value is null, then the getter returns the value of the report's default field's format (which will never be null. @author Jim Menard, jimm@io.com

postate.com/programming/vb-format.html">here. We have made the following enhancements to this specification:

• if the international currency symbol (¤) occurs in a format string, it is translated to the locale's currency symbol.
• the format string "Currency" is translated to the locale's currency format string. Negative currency values appear in parentheses.
• the string "USD" (abbreviation for U.S. Dollars) may occur in a format string.

One format object can be used to format multiple values, thereby amortizing the time required to parse the format string. Example:

 double[] values; Format format = new Format("##,##0.###;(##,##0.###);;Nil"); for (int i = 0; i < values.length; i++) { System.out.println("Value #" + i + " is " + format.format(values[i])); } 

Still to be implemented:

• String formatting (fill from left/right)
• Use client's timezone for printing times.

@author jhyde @version $Id: //open/mondrian-release/3.2/src/main/mondrian/util/Format.java#10 $

Abstract class to store known information about a given format.

Message format metadata.

Provides the default object for formatting the display of model objects in Velocity templates and JSP pages.

For Velocity templates a Format object is added to the Velocity Context using the name "format", while for JSP pages an instance is added as a request attribute using the same key.

For example the following Page code adds a date to the model:

 public void onGet() { Date date = order.deliveryDate(); addModel("deliveryDate", date); } 

In the page template we use the format object:

 Delivery date: $format.date($deliveryDate, "dd MMM yyyy") 

Which renders the output as:

Delivery date: 21 Jan 2004

The custom format class can be defined in the "click.xml" configuration file using the syntax:

 <format classname="com.mycorp.utils.MyFormat"/> 

After a Page is created its format property is set. The ClickServlet will then add this property to the Velocity Context.

When subclassing Format ensure it is light weight object, as a new format object will be created for every new Page. @see PageImports

Java 1.4 compatible enumeration of formats used for inventory printing.

{@link InventoryPrinter} services indicate supported formats listing any ofthese values in their {@link InventoryPrinter#FORMAT} serviceproperties.

Requestors of inventory printing indicate the desired output format by specifying the respective constant when calling the {@link InventoryPrinter#print(java.io.PrintWriter,Format,boolean)} method.

Round-tripping is guaranteed between the {@link #toString()} and{@link #valueOf(String)} methods.

Class to encapsulate XMLOutputter format options. Typical users can use the standard format configurations obtained by {@link #getRawFormat} (no whitespace changes),{@link #getPrettyFormat} (whitespace beautification), and{@link #getCompactFormat} (whitespace normalization).

Several modes are available to effect the way textual content is printed. See the documentation for {@link TextMode} for details. @author Jason Hunter @version $Revision: 1.10 $, $Date: 2004/09/07 06:37:20 $

Class to encapsulate XMLOutputter format options. Typical users can use the standard format configurations obtained by {@link #getRawFormat} (no whitespace changes),{@link #getPrettyFormat} (whitespace beautification), and{@link #getCompactFormat} (whitespace normalization).

Several modes are available to effect the way textual content is printed. See the documentation for {@link TextMode} for details. @version $Revision: 1.14 $, $Date: 2009/07/23 05:54:23 $ @author Jason Hunter

A non-public utility class similar to StringBuilder but optimized for XML parsing where the common case is that you get only one chunk of characters per text section. TextBuffer stores the first chunk of characters in a String, which can just be returned directly if no second chunk is received. Subsequent chunks are stored in a supplemental char array (like StringBuilder uses). In this case, the returned text will be the first String chunk, concatenated with the subsequent chunks stored in the char array. This provides optimal performance in the common case, while still providing very good performance in the uncommon case. Furthermore, avoiding StringBuilder means that no extra unused char array space will be kept around after parsing is through. @author Bradley S. Huffman @author Alex Rosen

The data format used for encoding the data in a {@link Dataset}.

There are a small number of formats provided. The default is {@link Formats#AVRO}, which is used when you do not explicitly configure a format.

@since 0.2.0

@author mh @since 17.01.14

is.org/docs/01-004.pdf">Grid Coverage specification 1.0 @author Martin Desruisseaux (IRD) @since GeoAPI 2.0

This class specifies the format for a given spreadsheet cell. @author Mark Murnane @author Martin Maher (Extended Style Support)

{@link Cell} format of the spreadsheet. @author henrichen

@author rflitcroft