Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 56122 invoked by uid 99); 21 Mar 2008 22:07:28 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 21 Mar 2008 15:07:28 -0700 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 21 Mar 2008 22:06:47 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 55EFA1A9832; Fri, 21 Mar 2008 15:06:58 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r639883 - /commons/proper/lang/trunk/xdocs/article2_4.xml Date: Fri, 21 Mar 2008 22:06:58 -0000 To: commits@commons.apache.org From: mbenson@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20080321220658.55EFA1A9832@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: mbenson Date: Fri Mar 21 15:06:57 2008 New Revision: 639883 URL: http://svn.apache.org/viewvc?rev=639883&view=rev Log: add EMF example; minor editing throughout Modified: commons/proper/lang/trunk/xdocs/article2_4.xml Modified: commons/proper/lang/trunk/xdocs/article2_4.xml URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/xdocs/article2_4.xml?rev=639883&r1=639882&r2=639883&view=diff ============================================================================== --- commons/proper/lang/trunk/xdocs/article2_4.xml (original) +++ commons/proper/lang/trunk/xdocs/article2_4.xml Fri Mar 21 15:06:57 2008 @@ -33,11 +33,12 @@ for more details. Instead users should use ObjectUtils.identityToString(StringBuffer, Object).

We also deprecated DateUtils.add(java.util.Date, int, int). It should have been private -from the beginning and please let us know if you actually use it.

+from the beginning; please let us know if you actually use it.

Before we move on - a quick note on the build - we built 2.4 using Maven 2 and Java 1.4. We also tested that the Ant build passed the tests -successfully under Java 1.3, and that the classes compiled under Java 1.2. As it's been so long, we stopped building a Java 1.1 compatible jar. Most importantly - it should be a drop in replacement for Lang 2.3, but we recommend testing first of course. Now... moving on.

Before we move on, a quick note on the build: we built 2.4 using Maven 2 and Java 1.4. We also tested that the Ant build passed the tests +successfully under Java 1.3, and that the classes compiled under Java 1.2. As it's been so long, we stopped building a Java 1.1-compatible jar. Most importantly, it should be a drop in replacement for Lang 2.3, but we recommend testing first, of course. Now... moving on. +

Three new classes were added, so let's cover those next.

@@ -52,7 +53,82 @@ FormatFactory interface, both found in the org.apache.commons.lang.text package.

Together they allow you to take the java.text.MessageFormat class further and insert your own formatting elements.

TODO: Insert example.

+By way of an example, imagine that we have a need for custom formatting of a employee identification +number or EIN. Perhaps, simplistically, our EIN is composed of a two-character department code +followed by a four-digit number, and that it is customary within our organization to render the EIN +with a hyphen following the department identifier. Here we'll represent the EIN as a simple +String (of course in real life we would likely create a class composed of department and number). +We can create a custom Format class: +


+public class EINFormat extends Format {
+  private char[] idMask;
+
+  public EINFormat() {
+  }
+  public EINFormat(char maskChar) {
+    idMask = new char[4];
+    Arrays.fill(idMask, maskChar);
+  }
+  public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {
+    String ein = (String) obj; //assume or assert length >= 2
+    if (idMask == null) {
+      return new StringBuffer(ein).insert(2, '-').toString();
+    }
+    return new StringBuffer(ein.substring(0, 2)).append('-').append(idMask).toString();
+  }
+  public Object parseObject(String source, ParsePosition pos) {
+    int idx = pos.getIndex();
+    int endIdx = idx + 7;
+    if (source == null || source.length() < endIdx) {
+      pos.setErrorIndex(idx);
+      return null;
+    }
+    if (source.charAt(idx + 2) != '-') {
+      pos.setErrorIndex(idx);
+      return null;
+    }
+    pos.setIndex(endIdx);
+    return source.substring(idx, endIdx).deleteCharAt(2);
+  }
+}
+

+Our custom EIN format is made available for MessageFormat-style processing by a +FormatFactory implementation: +


+public class EINFormatFactory implements FormatFactory {
+  public static final String EIN_FORMAT = "ein";
+  public Format getFormat(String name, String arguments, Locale locale) {
+    if (EIN_FORMAT.equals(name)) {
+      if (arguments == null || "".equals(arguments)) {
+        return new EINFormat();
+      }
+      return new EINFormat(arguments.charAt(0));
+    }
+    return null;
+  }
+}
+

+ +Now you simply provide a java.util.Map<String, FormatFactory> registry (keyed +by format type) to ExtendedMessageFormat: +


+new ExtendedMessageFormat("EIN: {0,ein}", Collections.singletonMap(EINFormatFactory.EIN_FORMAT, new EINFormatFactory()));
+

+As expected, this will render a String EIN "AA-9999" as: "EIN: AA-9999". +
+If we wanted to trigger the EIN masking code, we could trigger that in the format pattern: +


+new ExtendedMessageFormat("EIN: {0,ein,#}", Collections.singletonMap(EINFormatFactory.EIN_FORMAT, new EINFormatFactory()));
+

+This should render "AA-9999" as: "EIN: AA-####". +

+You can also use ExtendedMessageFormat to override any or all of the built-in +formats supported by java.text.MessageFormat. Finally, note that because +ExtendedMessageFormat extends MessageFormat it should work in most +cases as a true drop-in replacement. +

There were 58 new methods added to existing Commons Lang classes. Going through each one, one at a time would be dull, @@ -65,7 +141,7 @@

ClassUtils wrapper->primitive conversions are the reflection of the pre-existing primitiveToWrapper methods. Again easy to explain, they turn an array of Integer into an array of int[].

ObjectUtils identityToString(StringBuffer, Object) is the StringBuffer variant of the pre-existing identityToString method. In case you've not met tht before, it produces the toString that would have been produced by an Object if it hadn't been overridden. +

ObjectUtils identityToString(StringBuffer, Object) is the StringBuffer variant of the pre-existing identityToString method. In case you've not met that before, it produces the toString that would have been produced by an Object if it hadn't been overridden.

StringEscapeUtils CSV methods are a new addition to our range of simple parser/printers. These, quite as expected, parse and unparse CSV text as per RFC-4180.

@@ -86,8 +162,8 @@

The StringUtils class is a little large isn't it. Sorry, but it's got bigger.

- +

The StringUtils class is a little large, isn't it? Sorry, but it's gotten bigger. +

boolean containsAny(String, char[])
boolean containsAny(String, String)

Hopefully that was of interest. Don't forget to download Lang 2.4, or, for the Maven repositor users, upgrade your <version> tag to 2.4. Please feel free to raise any questions you might have on the mailing lists, and report bugs or enhancements in the issue tracker.

Hopefully that was of interest. Don't forget to download Lang 2.4, or, for the Maven repository users, upgrade your <version> tag to 2.4. Please feel free to raise any questions you might have on the mailing lists, and report bugs or enhancements in the issue tracker.