code: public static String escape( String str )
      {
          StringBuffer buf = new StringBuffer( str.length() * 2 );
          int i;
          for ( i = 0; i < str.length(); ++i ) {
              char ch = str.charAt( i );
              String entityName = SPECIAL_CHARS_NAMES_ARRAY.get( ( int ) ch );
              if ( entityName == null ) {
                  if ( ch > 0x7F ) {
                      int intValue = ch;
                      buf.append( "&#" );
                      buf.append( intValue );
                      buf.append( ';' );
                  } else {
                      buf.append( ch );
                  }
              } else {
                  buf.append( '&' );
                  buf.append( entityName );
                  buf.append( ';' );
              }
          }
          return buf.toString();
      }
docs: <p>
  Escapes the characters in a <code>String</code>.</p>
  <p/>
  <p>
  For example, if you have called addEntity(&quot;foo&quot;, 0xA1), escape(&quot;\u00A1&quot;) will return
  &quot;&amp;foo;&quot;</p>
  
  @param str The <code>String</code> to escape.
  @return A new escaped <code>String</code>.