JBuilder Util package concepts

General description

The com.borland.primetime.utilpackage contains many support classes that you might find useful when designing your own JBuilder OpenTools. The majority of these classes are public, yet they aren't fully documented as part of the OpenTools API. All of the classes Swing-based. These are the ones discussed here:


Detailed description of feature/subsystem

AssertionException

This class extends RunTimeException. Usually you use AssertionException in combination with Debug to test for and report self-check failures; however, you can use it by itself.
void doIt(String str) {
  try {
    AssertionException.assert(str != null, "null string input to doIt()");
   }
  catch (AssertionException ex) {
    ex.printStackTrace();
  }
}

CharsetName

CharsetNameprovides a routine which you can use to convert the internal file encoding name to an IANA name. Usually you use this for the "charset" string of a "meta" HTML tag.
String ianaName = CharsetName.javaToIANA(System.getProperty("file.encoding"));

CharToByteJava

CharToByteJava extends CharToByteConverter. It provides Unicode escape sequences instead of an UnknownCharacterException or character substitution. This class is used by JavaOutputStreamWriter.
static byte[] stringToByte(String text) {
  CharToByteJava c2bj = new CharToByteJava();
  int strlen = text.length();
  byte[] buffer = new byte[strlen * c2bj.getMaxBytesPerChar()];
  FastStringBuffer fsb = new FastStringBuffer(text);
  int nBytes = 0;

  try {
    nBytes = c2bj.convert(fsb.getValue(), 0, strlen, buffer, 0, strlen);
    byte[] b = new byte[nBytes];
    System.arraycopy(buffer, 0, b, 0, nBytes);
    buffer = b;
  }
  catch (Exception ex) {
    Debug.printStackTrace(ex);
  }
  return buffer;
}

ClipPath

Use this class to truncate a file pathname in the middle (substituting "...") if it exceeds a certain width.
String getDisplayNameForMenuItem(FileNode fileNode, int maxPixels) {
  String text = fileNode.getLongDisplayName();
  text = ClipPath.clipCenter(UIManager.getFont("MenuItem.font"), text, maxPixels);
  return text;
}

Debug

Debug is intended to help you debug your code during development. When you are ready to ship your code, just tell the compiler to exclude this class and re-compile.

Debug supports assertions. If enableAssert() has been used to enable them (assertions are on by default), a failed assertion results in an AssertionException being thrown. For example,

void doIt(String str) {
  try {
     Debug.assert(str != null, "null string input to doIt()");
  }
  catch (AssertionException ex) {
    ex.printStackTrace();
  }
}
Debug also provides support for tracing your code flow. If you call addTraceCategory() to enable a particular trace type, messages, stack traces, or conditional warning messages are output. You can display this output to System.err (the default) or to any other PrintStreamthat you define.
static final String TRACE = "MyTrace";

void test(String str)
  Debug.enableOutput(true);
  Debug.addTraceCategory(TRACE);
  doIt(str);
  Debug.removeTraceCategory(TRACE);
}

void doIt(String str) {
  Debug.trace(TRACE, "doIt() input str=" + str);
  Debug.warn(TRACE, str == null, "doIt()input str is null");
}
Debug also supports the debugging of paint logic. After painting, you can call the debugRect() method to draw a color-coded rectangle around the area. For example,
public void paintComponent(Graphics g) {
  Rectangle clip = g.getClipBounds();
  super.paintComponent(g);
  Debug.debugRect(g, clip.x, clip.y, clip.width, clip.height);
}

DummyPrintStream

DummyPrintStream extends PrintStream. Use it to redirect output that you want to suppress. For example,
static final String TRACE = "MyTrace";

void test(boolean bLog) {
  doIt(bLog ? System.out : new DummyPrintStream());
}

void doIt(PrintStream out) {
  out.println("my output");
}

FastStringBuffer

This class is an alternative to StringBufferfor those cases when you know a buffer is not shared. It avoids the complications of synchronization and sharing. Here's an example:
String expandCRLF(String s) {
  FastStringBuffer fsb = new FastStringBuffer(s);
  for (int i = 0; i < fsb.length(); ++i) {
    if (fsb.charAt(i) == '\r') {
      fsb.removeCharAt(i);
      fsb.insert(i, "\\r");
    }
    else if (fsb.charAt(i) == '\n') {
      fsb.removeCharAt(i);
      fsb.insert(i, "\\n");
    }
  }
  return fsb.toString();
}

JavaOutputStreamWriter

JavaOutputStreamWriter extends OutputStreamWriter. It writes characters to an output stream translating characters into bytes according to the given or current default character encoding. Characters that can't be represented in that encoding appear as Unicode escapes.
public void commit(FileNode node, String outText) {
  try {
    OutputStream os = node.getBuffer().getOutputStream();
    OutputStreamWriter osw = new JavaOutputStreamWriter(os, new CharToByteJava());
    osw.write(outText);
    osw.close();
  }
  catch (Exception ex) {
    Debug.printStackTrace(ex);
  }
}

OrderedProperties

OrderProperties extends Properties. It remembers the order in which properties are added and writes them in the same order. It writes international characters as Unicode escapes.

RegularExpression

RegularExpression provides simple expression pattern matching.
Url[] getPropertyFilesInPackage(FileNode fileNode) {
  RegularExpression regexp = new RegularExpression("*.properties");
  Url packageUrl = fileNode.getUrl().getParent();
  Url[] files = VFS.getChildren(packageUrl, regexp, Filesystem.TYPE_FILE);
}

SoftValueHashMap

This class extends java.util.HashMap. Your values to save are put in java.lang.ref.SoftReferencewrappers. This allows them to be garbage-collected at times of high memory demand. Therefore, a value stored using put() might later be returned as null when it's retrieved using get() if the value was garbage-collected. This is a way to implement a memory-sensitive cache if you can reproduce the objects.
private static Map myCache = new SoftValueHashMap();
public static synchronized MyValue getMyValue(Object myKey) {
  MyValue mv = (MyValue)myCache.get(myKey);
  if (mv == null) {
    mv = new MyValue(myKey);
    myCache.put(myKey, mv);
  }
  return mv;
}

Strings

Strings contains string manipulation routines which generally fall into two groups. The first are convenience wrappers for the java.text.MessageFormat.format() method, which builds the argument array for you based on input parameters. For example,
System.out.println(Strings.format("Project name is \"{0}\"", project.getDisplayName()));
The second group is associated with encoding and decoding strings so that they can be saved in a file and later restored. This includes escaping international and other characters such as delimiters. You can use the standard encoding or supply your own:
Strings.StringEncoding SPACE_TO_UNDERBAR_ENCODING = new Strings.StringEncoding(" _");
System.out.println(Strings.format("{0}={1}",
                   SPACE_TO_UNDERBAR_ENCODING.encode("string one"),
                   Strings.encode("string"));

VetoException

VetoException extends java.lang.Exception. Wizards use it to indicate a condition that needs correction before moving to the next step or starting or completing the Finish button processing. For example,
public void checkPage() throws VetoException {
  String text = jTextField1.getText().trim();

  if (text.length() == 0) {
    JOptionPane.showMessageDialog(this,
                                  "No string has been entered",
                                  "Error",
                                  JOptionPane.ERROR_MESSAGE);
    jTextField1.requestFocus();
    throw new VetoException();
  }
}

WeakValueHashMap

This class extends java.util.HashMap. Your values to save are put in java.lang.ref.WeakReferencewrappers. Such references don't prevent their referents from being garbage-collected. Therefore a reference stored using put() might later be returned as null when it's retrieved using get() if the referent object was garbage-collected. This is a way to implement a memory-sensitive cache if you can reproduce the objects.
private static Map myCache = new WeakValueHashMap();
public static synchronized MyValue getMyValue(Object myKey) {
  MyValue mv = (MyValue)myCache.get(myKey);
  if (mv == null) {
    mv = new MyValue(myKey);
    myCache.put(myKey, mv);
  }
  return mv;
}