STBC Help

Help and configuration for the STBC.

• Help
  • Description
  • Usage
  • Compilation Result
  • Line Count
• Configuration
  • Configure at runtime
  • Configure externally - webstart
  • Configure externally - application
  • Add the compiler to the application's runtime classpath

Help

Description

The STBC GUI shows the class name field and line count label across the top, the source code text area in the center, then a row of buttons to Compile & Browse to compiler and lastly the output text area on the bottom.

When STBC first appears, it shows the classpath of the current runtime and the compiler class name that will be used if STBC needs to directly load the compiler. The latter is significant in that the value can be changed as a runtime argument.

Usage

To begin, paste code into the main text area.

When the source of the text area changes, STBC makes a guess at the public class name and updates the line count. If it guesses the class name incorrectly, change the name in the text field above the main text area. Note that every time the user types characters or pastes text into the source field, STBC will guess the name, so it is best not to edit the class name value until ready to Compile.

Once the code is in the text area, and the class name has been checked/corrected, click the Compile button to invoke compilation of the source with standard options.

If a compiler is not found, STBC will prompt you to browse to the tools.jar of a JDK. It is also possible to set this path using the Browse to compiler button. This path will be ignored if a compiler is found in the current runtime. See the section on configuring the (tools.jar path) at runtime for further details.

If a compiler is found or has been configured, clicking Compile will invoke compilation (disabling the input elements for the duration of the compile) then report the results in the output text area.

Compilation Result

If the code compiled without error, the message will be.

Compiled without errors: true

Otherwise, the output will look more like a typical javac output.

string:///HelloWorld.java:4: cannot find symbol
symbol  : method prinltn(java.lang.String)
location: class java.io.PrintStream
    System.out.prinltn("Hello World!");
              ^
1 error
Compiled without errors: false

Note that the final line only reports errors, and the compilation is not set up to force unchecked or deprecated warnings, so code calling Component.show() might report.

Note: string:///HelloWorldFrame.java from JavaSourceFromString
    uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Compiled without errors: true

Fix deprecation errors before posting code. The JavaDocs for each deprecated class or member usually identifies the replacement. Try to fix unchecked cast warnings, though some of those are unavoidable when the code uses generics (the compiler source includes one!).

Line Count

The line count label on the top right of STBC has a border that is colored according to the line length of the code sample.

The colors start at green for short 001, go through yellow for medium 150, orange for long 250 & red for very long 500. Code samples should ideally be kept in the green (short!). Note that the values where the colors change were chosen by the author and are quite arbitrary. Since the limits will be different depending on the forum/audience and the nature of the example, the colors are intended only as a guide.

Having said all that. It is best not to make very long code lines, just to make the line count shorter. The point is to look more closely at the example and discover what else can be removed, yet still compile and show the problem or make the point. Most examples can be expressed in under 100 code lines even when:

• using specific (not package) imports
• including white space between methods and sections
• including JavaDoc & inline comments where needed
• showing codes lines that have moderate indent (using spaces, not tabs) & are hard wrapped before 80 chars.

Making a well formatted, short example is a little tricky, so we provide a number of tools to help. While the STBC is for checking that code will compile, a better tool for checking text line width is the Text Width Checker.

Configuration

Configure at runtime

If STBC is invoked to Compile source but cannot locate a compiler, it will prompt the user to browse to a compiler external to the current JRE. The user can also activate the Browse to compiler button to do the same. The file chooser will open pointing to the directory specified as java.home for the current JRE - this should make it easy to browse to a JDK if they are all installed under one directory.

The compiler would typically be found in the tools.jar located in the lib directory of a JDK (e.g. in pseudo-paths ${jdk}/lib/tools.jar).

If a custom path is defined, it will be stored in a properties file for future reference**. The properties file will be written to ${user.home}/org/pscode/tool/dev/stbc/stbc.properties. The package name of the main class is used as a basis for the path, in order to avoid path/name clashes with properties files from other apps.

** In fact, if a compiler has already been loaded, any change to the path to the compiler will not come into effect until the next time the application is invoked.

STBC will always check for the internal compiler (of its own JRE) first. If found, the compiler/path defined in the properties file will be ignored.

Configure externally - webstart

The path can also be configured from the Java Control Panel.

Using windows, you would open the control panel then open the Java item to get the JCP.

Once the JCP is open, select the Java tab and View the Java Application Runtime Settings.

Ensure a JRE that has access to a tools.jar is Enabled for use. If no suitable JRE is listed, click Find/Add to locate or add an existing JRE.

The author tested this option, but quickly saw the downside. Having recently installed a beta JRE to test new, experimental functionalily, the changeover to the older JDK halted further testing (short of changing the enabled JRE whenever swapping between STBC and testing new functionality).

We recommend setting the path at runtime, and only if prompted to do so.

Configure externally - application

Set java.home to point to a JDK.

We recommend setting the path at runtime, and only if prompted to do so.

Add the compiler to the application's runtime classpath

The STBC uses an URLClassLoader to gain access to the tools.jar.

Posts on the Sun forum support that if the tools.jar is added to the classpath of an applet or webstart app., the compiler will be found using the application classloader.

Given the tools archive is over 11 Meg at current version (Java 6), it is impractical for most purposes to supply it with the application.

Either way, it probably violates Sun's distribution licence. But we are not lawyers, and since we have no interest in supplying this huge archive to developers who should have a JDK anyway, it is of no interest to us to investigate that avenue further.

Of course, it would be handy if Sun itself offered the tools.jar as a webstart extension - just for those occasional cases where it makes sense to add it directly to the application classpath. This would remove the question of legality, save deployers the bandwidth of serving it, and also allow Sun to retain control over the installation (with EULA if needed) and versioning of the tools API.

And to all of you who desperately want to see the tools.jar distributed with the JRE, please post a bug report/RFE outlining your case. We will be happy to vote against it. It is a huge whack of extra download just to get a Java runtime, and compiling Java source is something primarily of interest to developers - end users don't need it one iota.