Zelix KlassMaster - Documentation

The existingSerializedClasses Statement

The ZKM Script existingSerializedClasses statement ensures that any changes made to the specified classes by subsequent Zelix KlassMaster™ trim and obfuscate statements will not break already existing serialized objects that are based upon the non-obfuscated class definition. For each class matched by the statement, Zelix KlassMaster™ will
  • add name exclusions for
    1. the fully qualified name of the class
    2. the name of every field contained or inherited by the class
    3. the fully qualified class name of the type of each non-primitive field contained or inherited by the class
  • add a serialVersionUID field to the class (if it doesn't already exist) set to a value based upon the non-obfuscated class definition.

The statement has no impact in the case of specified classes that don't directly or indirectly implement java.io.Serializable. Successive existingSerializedClasses statements (in the same script) have a cumulative effect. Once an existing serialized class has been specified the only way to remove the specification is with a resetExistingSerializedClasses statement.

Explanation and Examples

Put informally (with mandatory components in bold), the syntax for a class exclusion parameter is:
<classAnnotations> <classModifiers> "<archiveQualifier>"!<packageQualifiers>.<className> <extendsClause> <implementsClause>;

For a class to be treated as a pre-existing serialized class, all of the following must be true:
  • Its annotations must match any specified annotations.
  • Its modifiers (e.g. public final) must match all parameter modifiers. So if the parameters are public abstract !interface then the class must be public, abstract and NOT an interface to be excluded.
  • If the parameter has an archive qualifier then the class must be contained in an archive which matches that archive qualifier.
  • Its package qualifiers must match any specified package exclude parameter component. If there is no package exclude parameter component then the class must be in the default package.
  • Its unqualified name must match the parameter's class name specifier.
  • If the parameter has an extends clause then the class must be a subclass of the specified class
  • If the parameter has an implements clause then the class must directly or indirectly implement all of the specified interfaces
           pack2.Class1 and //Treat class pack2.Class1 as an existing serialized class
           pack3.* and //Treat all classes in package "pack3" as existing serialized classes
           //Treat all classes contained in a JAR file with a name matching "MyJar*.jar" as existing serialized classes
           "MyJar*.jar"!*.* and 
           //Treat all classes annotated which a class matching *.MyAnnotation0 as existing serialized classes
           @*.MyAnnotation0 *.*;  


"existingSerializedClasses" classExcludeParameter ("and" classExcludeParameter )* ";"

annotationSpecifier ::= ("@" [packageExcludeParameter] nameSpecifier) | annotationSpecifierAndList

annotationSpecifierAndList ::= ["!"] "(" annotationSpecifierOrList ("&&" annotationSpecifierOrList)* ")"

annotationSpecifierOrList ::= annotationSpecifier ("||" annotationSpecifier)*

classExcludeParameter ::=
   [annotationSpecifier] [["!"] "public" | "package"]
   [["!"] "abstract"] [["!"] "final"] [["!"] "interface"] [["!"] "synthetic"] [["!"] "enum"] [["!"] "annotation"]
   ["\"" archiveQualifier "\"" "!"] [packageExcludeParameter] nameSpecifier [containingClause]
   [extendsClause] [implementsClause]

extendsClause ::= "extends" [annotationSpecifier] wildcardClassName

fullyQualifiedClassName ::= name ("." name)*

implementsClause ::= "implements" [annotationSpecifier] wildcardClassName ("," [annotationSpecifier] wildcardClassName)*

name ::= (["0"-"9","a"-"z","A"-"Z","$","_"])+
   i.e. a Java identifer (e.g. a package, class, field or method name) with no wildcards allowed

nameAndList ::= ["!"] "(" nameOrList ("&&" nameOrList)* ")"

nameOrList ::= nameSpecifier ("||" nameSpecifier)*

nameSpecifier ::= wildcardName | nameAndList

packageExcludeParameter ::= packageName | packageNameAndList

packageName ::= wildcardName ("." wildcardName)* "."
   NB: the final "." is part of the package name

packageNameAndList ::= ["!"] "(" packageNameOrList ("&&" packageNameOrList)* ")"

packageNameOrList ::= packageExcludeParameter ("||" packageExcludeParameter)*

wildcardClassName ::= wildcardName ("." wildcardName)*

wildcardName ::= (["*","0"-"9","a"-"z","A"-"Z","$","_"])+
   i.e. a Java identifer (e.g. a package, class, field or method name) with the "*" wildcard allowed
Where archiveQualifier is a relative or absolute archive path name with the "*" wildcard allowed. E.g. "/lib/*.jar" or "myJar0.jar"
ZKM Script resetStringEncryptionExclusions statement The ZKM Script Language ZKM Script resetExistingSerializedClasses  statement