JCloaktm

Version 3.5.3 README

 

Installation

System Requirements

JCloak can run on any system that supports Javatm 2.

Java is available from the following sources:

Installation - Solaris/Unix

Unpack the gziped tar file into any installation directory you choose.  The JCloak.sh file will start the command line JCloak.  To run the GUI use the -show option.

To register your copy of JCloak from command line mode you may use the command 'JCloak -register <serial>', specifying your demo or purchased serial number.

Installation - Windows

Run the self-extracting installer, install.exe.  This will prompt for an installation directory and unpack JCloak into the specified directory.   If you do not have Java 2 installed then you must either:

The third option is allows Window's users to install the Java 2 runtime local for JCloak only. The installer does not affect the Window's registry.

To run JCloak in command mode use the JCloak.exe program.  To run in GUI mode use JCloakGUI.exe. 

New Features

Compatibility

JCloak Version 3.x configuration files (called a project file in Version 3.0) are compatible with all previous versions with a few minor exceptions.

MainClass

In previous JCloak versions the MainClass() directive was used to specify either an Application class (defining main()) or an Applet derived class.  In version 3.0 the MainClass() directive is used only for Applications, the MainClass directive will indicate the main() for executeable Jar files.  If you are using MainClass() for an Applet, change to the ClassSettings() directive specifying the class as 'Externally Referenced', for example:

If 'com.acme.MyApplet' is the Applet class for your applet and you have:

MainClass("com.acme.MyApplet")

change it to:

ClassSettings("com.acme.MyApplet", true)

or if MyApplet runs as both an Application and an Applet, and MyApplet defines main(), use both directives:

MainClass("com.acme.MyApplet")
 ClassSettings("com.acme.MyApplet", true)

Resource Inclusion

JCloak will now scan for resources for each package it loads on a classpath.  This means it will include 'jpeg', 'gif', etc. files found on the classpath in the directory for each package.  If a package does not require resource but resources are located in the classpath under that package you can block all resource inclusion with the 'PackageResourceSearchSettings()' directive.

The obfuscate for JCloak blocks resource loading from the unnamed default package with this directive:

PackageResourceSearchSettings("", false)

Command Line Arguments

The command line arguments for specifying classpath and obfusation settings are no longer supported.   The new classpath features are only available from the configuration file.  The configuration file can be specified as an argument for both the GUI and the command line.

ClassPath 

The AddWriteablePath() and AddTargetClassPath() directives are being phased out.  The new directive AddToClassPath() is hopefully easier to understand.  There is one incompatibility some configurations may run into:

In JCloak Version 3.0 the classpath must be fully specified in the project file using AddToClassPath(<path>, <include>, <obfuscate>).  The new directive is AddToClassPath(<path>, <include>, <obfuscate>), the affect is: There is no default classpath.  All classpath entries including the JDK must be named in an AddToClassPath() directive.  Packages found on the named classpath entry are marked and treated as defined in the following table:

Include Obfuscate Resulting Operation
false false Classes are only used for reference to determine if methods are safe to obfuscate. These classes are assumed to be immutable, for example the java.* classes.
false true Classes are obfuscated with the rest of the classes, but are never written to the output.  This can be used to support incremental obfuscation, where for example an optional library is shipped separate from the main product.
true false All classes found on this classpath are included in the output yet no obfuscation is performed on them.  These classes are treated like reference classes except they are included in the output.  This could be used to include a thirdparty library un-molested in your output jar file.  The GUI makes this the default setting for new classpaths.
true true All classes found on this classpath are loaded and fully obfuscated.  If the obfuscated project is an Applet or Application and remove un-referenced classes option is set only the classes referenced are saved to the output.  Individual classes or packages can be marked as dynamically loaded (via forName()) in which case they are treated as referenced and saved to the output.

 

ClassSettings/PackageSettings

The ClassSettings and PackageSettings have been changed starting with V3.3, formerly the syntax was:

ClassSettings(<class-name>, <symbol-access-level>, [preserve-class-name]);

The new format is:

ClassSettings(<class-name>, <symbol-access-level>, [class-access-level], [jave-beans-setting]);

JCloak will read the pre-V3.3 format and automatically convert it to the V3.3 format. The class-access-level argument expands on the capabilities of the former preserve-class-name argument. A class-access-level setting of none is equivalent to setting preserve-class-name to true.

The same change was made to the PackageSettings preserve-class-name argument.

Fixed Bugs

V3.5.3
'Invalid reference warning printed for inherited field
JCloak does not properly handle inherited field references produced by some of the java compilers (including javac). The renaming portion of JCloak does detect the problem and print the warning: "WARN: Class 'class-ref' contains invalid reference to 'field-ref'". Note 'field-ref' is replaced with a reference to a named field inherited from a superclass, 'class-ref' is the class referencing the superclass field.
V3.5.2
Resources not saved to output JAR
When JCloak loaded a resource file (.gif, .properties, ...) from a classpath, and could not associate it with a package it was not saved with the obfuscated output. JCloak now saves all resources loaded from the source classpath if that classpath is included with the obfuscated output.

To disable resource inclusion entirely you can set the default resource file extensions to an empty list (see SetResourceFileExtensions(), in the JCloak manual command line section)

V3.5.1
Corrupt project file on save of new project
The first time a new project file was saved from the GUI version of JCloak the project file was corrupted.
V3.4.2
Package/Class settings not honored with non-default JavaBean settings
Any package or class access level settings would not override the global setting if a JavaBean setting other than 'unspecified' is used.
V3.3.2
Field/Method not obfuscated
In some cases JCloak does not obfuscate all the references to certain fields or methods when it processes classes generated by Metrowerks CodeWarrior Pro 5/6. JCloak works around this compiler bug in this version. The bug has been reported to Metrowerks.
 
throws 'Error: Attempt to ofuscate ... but is already obfuscated'
In some cases when JCloak processed an interface method that is implemented by an inherited method JCloak will throw this error.
V3.3.1
Field obfuscated incorrectly
If obfuscation is generated from the GUI, and a settings change caused a field to transition from obfuscateable to not obfuscateable JCloak could generate an invalid obfuscated field name.
V3.3
Method not obfuscated.
If an abstract method from a super-class implemented an interface method declared by a derived class the super-class method was not properly obfuscated.
V3.2.9/10
Memory consumption reduced.
JCloak now uses less memory each obfuscation run. The memory frees up more quickly as well so multiple runs from the GUI perform better.
V3.2.7
"Preserve Public Symbols" in class and package settings popup (GUI)
The popup menu item "Preserve Public Symbols" for a class or package did not set the access modifier correctly. Modifier was set to PUBLIC, not PACKAGE as it should be.
Poor GUI performance when updating obfuscation settings
When updating obfuscation settings from the GUI JCloak would put up a rather confusing dialog then not display progress as it updated the obfuscation. Several fixes in this area to improve GUI responsiveness:
Fix JCloak to reports a warning if same class found on different classpath.
JCloak would silently ignore the class found on a later classpath, now it warns you.
V3.2.6
serialVersionUID obfuscated if not private access
JCloak only preserved the serialization version if the field matched the Serialzation specification exactly. This has been relax such that JCloak will preserve the serialVersionUID field, even if it is not private access.
V3.2.5
RemoveUnreferencedSymbols(true) causes Error to be thrown
JCloak threw the Error "Method ... removed and it implements interfaces" when RemoveUnreferencedSymbols is enabled and a removed interface method is overriden by a subinterface method with the same signature and throws list.
Stack trace when class load fails
Improved error handling, Detects more class loading and corrupted class problems and prints an error message, not just a stack trace.
Can not add a 'MainClass' from the GUI
Fixed to allow setting from right click (context sensitive popup) on class in tree.
V3.2.4
All classnames not propertly matched from loaded name map.
Fix bug that caused JCloak to ignore the class name loaded from the name map when the class had no obfuscateable symbols.
V3.2.3
Error throw when loading name map
Fix bug in using symbol map file, caused error thrown for renaming to same name.
NullPointerException when loading name map
Under certain conditions loading a symbol name map would cause a NullPointerException in JCloak.
V3.2.2
Unamed package classes not renamed correctly
When package rename blocked, class in unnamed package gets an improper name.

Known Issues

The latest list of is on the Force 5 website.

The following list of problems existed a press time:

Buttons in the new project wizard displayed too small on Solaris
On Solaris 7 systems the navigation buttons on the JCloak new project appear too small to read the text. The problem occurs with certain X servers and font selections. There is no current workaround. The button order is 'back' 'next' 'cancel' 'help'.

RemoveUnreferencedClasses(true) and RemoveUnreferencedSymbols(true) are incompatible with LoadReferencedClassesOnly(false)
Removing unreferenced classes or symbols may fail when JCloak is instructed to load the entire classpath (with LoadReferencedClassesOnly(false)). It is recommended that you set LoadReferencedClassesOnly(true) to use these two directives to remove dead code.

Reporting Bugs

Thank you for taking the time to help us make JCloak a better product.  We really apreciate your feedback, the bug we don't hear about may never get fixed.

We try to promptly answer all bug reports with a work-around and/or a release in which the bug will be fixed.

We are always happy to hear about bugs, please, it's the bugs we don't hear about that cause problems. 

You can now report bugs in one of two ways:

  1. By using the GUI menu item 'Help:Report Bug'.
  2. Report bugs by sending E-Mail to JCloakSupport@force5.com.

When you report bugs by sending E-Mail, Please include at minimum the following information: