<!-- use all jars in the input-lib-dir directory and obfuscate them
          to *_obf.jar -->
  <inoutpairs resources="auto">
    <fileset dir="${input-lib-dir}">
      <include name="myapp*.jar"/>
      <exclude name="*_obf.jar"/>
    </fileset>
    <mapper type="glob" from="*.jar" to="*_obf.jar"/>
  </inoutpairs>

  <!-- the above mapper is the default one so the following snippet does the same -->
  <inoutpairs resources="auto">
    <fileset dir="${input-lib-dir}">
      <include name="myapp*.jar"/>
      <exclude name="*_obf.jar"/>
    </fileset>
  </inoutpairs>

If the jar to be processed by yGuard depends on external classes or libraries, this element can be used to specify classpaths to these entities. These libraries will neither be shrinked nor obfuscated. Use the inoutpair element for this purpose! See example 4 later in this document for an example of when to use this element.
In order to achieve a maximum shrinking effect by the shrink task, all external dependencies should be declared in the externalclasses element. Otherwise, all non-private methods of classes that inherit from unresolvable classes will not be shrinked.

The elements attributes and child elements can be seen on the Ant documentation page about using path elements.

Using the attribute element, you can specify which attributes present in the input classes should be kept in the obfuscated output classes.
See example 6 later in this document for an example of when to use this element.

Child Elements

• patternset

An example:

    <attribute name="SourceFile, LineNumberTable, LocalVariableTable">
      <patternset>
        <include name="com.mycompany.mylibrary.**"/>
      </patternset>
    </attribute>

This will retain the attributes named "SourceFile", "LineNumberTable", and "LocalVariableTable" effectively enabling debugging information for all classes in the com.mycompany.mylibaray package and subpackages.

The shrink task removes all classes, fields and methods that are not reachable from a number of entrypoints given by a nested keep element.
See the Complete Examples section for explanation of some common use cases. If your code uses reflection, please read the General Hints & Troubleshooting section for information on this topic.

Child Elements

• keep
• entrypointjar

The entrypointjar element can be used for convenience if your application uses libraries that are to be shrinked, but the jarfile using these libraries should be left untouched by the shrinking engine. Such a jarfile could be specified as an entrypointjar.

Child Elements

The entrypointjar element has no child elements.

Example

      <yguard>
        <inoutpair in="lib-in.jar" out="lib-out.jar" />
        <shrink>
          <entrypointjar name="myApp.jar"/>
        </shrink>
      </yguard>

The basic idea is, that all elements will be renamed by this task. There are different use cases, where you sometimes want to exclude or simply just have to exclude some elements from name obfuscation, i.e. not rename them but keep in the API as is. See the Complete Examples section for explanation of some common use cases. If your code uses reflection, please read the General Hints & Troubleshooting section for information on this topic. Excluding elements can be achieved by using the keep element, the mainclass attribute of the rename element and by annotating elements in the source code with the annotation that is specified in the annotationClass attribute of the rename element. Using the nested keep element, you have to specify all classes, methods, fields, and attributes that should be excluded from name obfuscation. Another way is to annotate the elements directly in the source code that should be obfuscated or excluded. You can use the yFiles obfuscation annotation com.yworks.util.annotation.Obfuscation for that or specify your own annotation in the annotationClass attribute of this element.

Child Elements

• keep
• property
• patch
• adjust
• map

property elements can be used to give hints to the name obfuscation engine. Depending on the exact version of yGuard, the task may use these hints to control the process of obfuscation.

Child Elements

The property element has no child elements.

This element is a child of the rename or shrink element. It can be used to specify elements that are excluded from the parent rename or shrink task. The excluded classes, methods and fields are defined using nested package, class, method and field elements.
The elements given in the keep element are considered as code entrypoints. All code reachable from these entrypoints will be implicitly excluded from shrinking, too.

Common Child Elements

• class
• method
• field
• package

Child Elements only available in the rename task

The rename task allows for a special treatment of the linenumbertable and sourcefile attributes. This treatment can be specified in the following child elements:

• sourcefile
• linenumbertable

The class element can be used for excluding certain classes and/or their fields and methods from the renaming or shrinking process.
If no name, extends or implements attribute is given and the class element contains no nested patternset, a class element matches all class names.

The classes, methods and fields attributes tell the shrinking and renaming engines which classes, methods and fields to keep based on their visibility. The following table lists the possible values for all of these attributes and shows which elements will be excluded. A '*' denotes, that elements that have the given visibility will be excluded for the specified attribute value. A '-' denotes that the these elements will not be excluded from the process.

Child Elements

• patternset

Explanation

There are three possible ways of specifying which classes will be excluded from the shrinking and obfuscation process:

1. One can specify a single java class using the fully qualified name in java syntax with the name attribute. For example:

   <class name="mypackage.MyClass"/>

2. One can specify multiple java classes using a modified version of a patternset. The patternset's includes and excludes element should use java syntax, but the usual wildcards are allowed. Some examples:

         <class>
           <patternset>
             <include name="com.mycompany.**.*Bean"/>
             <exclude name="com.mycompany.secretpackage.*"/>
             <exclude name="com.mycompany.myapp.SecretBean"/>
           </patternset>
         </class>

   This will expose all classes which reside in the package subtree of com.mycompany and whose name ends with Bean except for those, that reside in the com.mycompany.secretpackage package and the single SecretBean in com.mycompany.myapp.

         <class>
           <patternset>
             <include name="com.mycompany.myapp.MainClass"/>
             <include name="org.w3c.sax?."/>
             <exclude name="org.w3c.sax?.**.*$$*"/>
           </patternset>
         </class>

   This will expose the MainClass class and all classes, which reside in packages like org.w3c.sax1, org.w3c.sax2, org.w3c.saxb except for inner classes. '$' is used as a separator between outer class names and inner class names. Since Ant uses '$' as an escape character, you have to use two consecutive '$'s ('$$') if you want to pass one as an argument to the task.
3. Finally one can specify classes depending on their visibility, i.e. depending whether they have been declared public, protected, package friendly or private (inner classes). This can be achieved by additionally specifying the classes attribute in the class element.

         <class classes="protected">
           <patternset>
             <include name="com.mycompany.myapi."/>
           </patternset>
         </class>

   This will keep all class names, that are either public or protected and which reside in one of the subpackages of com.mycompany.myapi (note the abbreviation: the trailing dot behaves like the trailing '/' in the usual patternset, i.e. it could be rewritten as com.mycompany.myapi.**.*)

         <class classes="protected"
           methods="protected"
           fields="protected">
           <patternset>
             <include name="**.*"/>
           </patternset>
         </class>

   This example shows the very common use case of excluding a complete public API from the shrinking and obfuscation process. There is an abbreviation for this use case: you can omit the patternset element, since in the case where the classes attribute is specified and there is no patternset child element used, the task will automatically apply this rule. In this example all classes will be exposed, that are either public or protected. Their methods and fields will be exposed as long as they are declared public or protected. If a class is package friendly or private (inner classes), neither itself nor its methods or fields will be exposed.

   The last example shows how to keep the public methods of certain classes only, but neither field names nor the class names themselves.

         <class classes="none" methods="public" fields="none">
           <patternset>
             <include name="com.mycompany.myapi."/>
           </patternset>
         </class>

Using the method element you can specify methods by signature which should be excluded from shrinking or name obfuscation.

Child Elements

• patternset

Examples

    <method class="com.mycompany.myapp.MyClass"
      name="void main(java.lang.String[])"/>
    <method class="com.mycompany.myapp.MyClass"
      name="int foo(double[][], java.lang.Object)"/>
    <method name="void writeObject(java.io.ObjectOutputStream)">
      <patternset>
        <include name="com.mycompany.myapp.data.*"/>
      </patternset>
    </method>
    <method name="void readObject(java.io.ObjectInputStream)">
      <patternset>
        <include name="com.mycompany.myapp.data.*"/>
      </patternset>
    </method>

This will keep the main method of the MyClass class and the foo method. Additionally all readObject and writeObject methods (used for Serialization) will be kept in all classes of the com.mycompany.myapp.data package. Note that you have to specify the return argument's type, even if it is void and that you have to use the fully qualified name for all classes, even those, that are in the java.lang package.

Using the field element you can specify fields by name which should be excluded from shrinking or name obfuscation.

Child Elements

• patternset

Examples

    <field class="com.mycompany.myapp.MyClass" name="field"/>
    <field name="serialVersionUID">
      <patternset>
        <include name="com.mycompany.myapp.data.*"/>
      </patternset>
    </field>

This will keep the field named 'field' of the MyClass class. Additionally all the serialVersionUID fields (used for Serialization) will be kept in all classes of the com.mycompany.myapp.data package.

The package element can be used for excluding certain package's names from the renaming process. It cannot be used for the shrinking process.
All packages that are matched be the nested patternset element will not be obfuscated. This has no influence on the class, method, or field names but will only result in the package's name not being obfuscated. Normally, it is not necessary to use this element, instead the class element is used to keep class names (and thus their package names) from being obfuscated.

Child Elements

• patternset

Examples

    <package>
      <patternset>
        <include name="com.mycompany.myapp.*"/>
      </patternset>
    </package>

This will keep the names of all packages that are direct descendants of com.mycompany.myapp. This will not influence the names of the classes contained in these packages.

The sourcefile element allows for a special treatment of the sourceFile attribute by the rename element.
Using nested property elements, the mapping of sourceFile elements in obfuscated class files can be adjusted.

Child Elements

• property
• patternset

Examples

    <sourcefile>
      <property name="mapping" value="y"/>
      <patternset>
        <include name="com.mycompany.myapp.**"/>
      </patternset>
    </sourcefile>

This will map all of the source file attributes in the packages below com.mycompany.myapp to " y", which is small and generally a nice letter.

The linenumbertable element allows for a special treatment of the linenumbertable attribute by the rename.
Using nested property elements, the mapping of linenumbertable elements in obfuscated class files can be adjusted.

Child Elements

• property
• patternset

Examples

  <linenumbertable>
    <patternset>
      <include name="com.mycompany.myapp.**"/>
    </patternset>
  </linenumbertable>

This will keep the line numbers of all the classes in the com.mycompany.myapp packages and subpackages. Note that in order to see the line numbers in stacktraces, the sourcefile attribute has to be retained for those files, too, since otherwise the JDK will display "Unknown source. " for the stack elements.

  <linenumbertable>
    <property name="mapping-scheme" value="scramble"/>
    <property name="scrambling-salt" value="1234"/>
    <patternset id="CompanyPatternSet">
      <include name="com.mycompany.myapp.**"/>
    </patternset>
  </linenumbertable>
  <sourcefile>
    <property name="mapping" value="y"/>
    <patternset refid="CompanyPatternSet"/>
  </sourcefile>

This will keep scrambled line numbers for all classes found in and below the com.mycompany.myapp packages. The scrambling algorithm will use the given "salt" value to use a predefined scrambling scheme. In order to see the scrambled line numbers, a sourcefile element is used on the same patternset, which is referenced by its previously declared reference id, to rename the source files to "y".

Using the adjust element one can specify resource files whose names and/or contents should be adjusted by the rename engine to reflect the obfuscated class names.
Note: This will only adjust files that are part of the inoutpair jars! I.e. the fileset's root directory is the combined root of all jars that are passed to yGuard via the inoutpair elements. yGuard will not modify any of the files on disk, except for the out-jar!

Child Elements

The adjust element can be used just like the standard Ant ZipFileSet element.

Some examples:

    <!-- adjust the names of all java property files in the jars -->
    <adjust replaceName="true">
      <include name="**/*.properties"/>
    </adjust>

    <!-- adjust the classnames specified within a single XML file in the jar -->
    <adjust file="plugins.xml" replaceContent="true" />

    <!-- suppress the adjustment of the resource path
    com/mycompany/myapp/resource in the jar. -->
    <!-- the package com.mycompany.myapp still gets obfuscated. -->
    <adjust replacePath="false">
      <include name="com/mycompany/myapp/resource/*"/>
    </adjust>

The map element is an immediate optional child of the rename element. It can be used to specify the mapping for the renaming process directly. This is an advanced topic.

Child Elements

• package
• class
• method
• field

All of these elements use the name attribute to specify the specific element. The method and field element need the class attribute in order to function properly. Neither wildcards nor nested patternset elements are allowed. Use the map attribute to specify the new name (subpackage, classname, methodname and fieldname respectively).
Some examples:

    <map>
      <package name="com" map="etc"/>
      <package name="com.mycompany" map="nocompany"/>
      <package name="com.mycompany.myapp" map="asdf"/>
      <class name="com.mycompany.myapp.MainApp" map="foo"/>
      <method class="com.mycompany.myapp.MainApp"
        name="void main(java.lang.String[])" map="bar"/>
      <field class="com.mycompany.myapp.MainApp" name="field" map="a"/>
    </map>

In this example the package structure 'com.mycompany.myapp' will be obfuscated to 'etc.nocompany.asdf'. The MainApp class will be called 'foo' and its main method will be remapped to 'bar' (and can therefor not be executed from commandline anymore). The field called 'field' will be renamed to 'a'.

In order to exclude certain elements from obfuscation, it is possible to use annotations in the source code instead of listing those elements in the keep element.

Any annotation class can be used for this, but it must be specified in the annotationClass attribute of the rename element and follow the convention as explained below to work. yGuard contains such an annotation in the distribution package ready for use. The annotation class is com.yworks.util.annotation.Obfuscation and can be found in the yGuard distribution in the lib/ObfuscationAnnotation.jar. Feel free add this attribute definition to your own codebase and possibly adjust the package name to your needs. Here is the source code for it:

Obfuscation.java

package com.yworks.util.annotation;

public @interface Obfuscation {

  boolean exclude() default true;

  boolean applyToMembers() default true;
}

This class is also the default annotation yGuard is looking for when obfuscating.

The convention for annotation classes that yGuard understands as obfuscation controlling annotations requires two attributes:

The true power of the map element lies in its use together with the patch element, which itself is a child element of the rename top level element.

Attributes

The yguard element has no attributes.

Child Elements

• class

Using the patch element one can generate jars, that can be used to serve as patches for versions of an application that have already been deployed in obfuscated form. During the main obfuscation run, yGuard produces an xml-logfile, in which the mapping between the unobfuscated and obfuscated names is contained. The patch element is used to declare a set of classes, that need to be patched. During the obfuscation, yGuard will include those files in the obfuscated jars only, that are declared inside this element.
For example:

    <patch>
      <class name="com.mycompany.myapp.MainClass"/>
      <class>
        <patternset>
          <include name="com.mycompany.myapp.bugs.*"/>
        </patternset>
      </class>
    </patch>
    <map logfile="yguardlog.xml"/>

This will only include the MainClass class and all classes that belong to the bugs package in a patch jar. In order to work with the previously delivered obfuscated version, it is important to use the map element to specify the mapping of the elements from the previous run. This can most conveniently be achieved by specifying the log file from the corresponding run in the map's logfile attribute.

There will be some examples given, that represent common use cases.

Example 1: Getting started with Ant and yGuard (for Ant newbies)

Following are the contents of a complete build.xml file. Just copy the following lines to a new document named build.xml, put the file into your project's root directory and edit the file to suit your needs.

  <?xml version="1.0" encoding="UTF-8"?>
  <!-- file build.xml in your project root directory -->
  <!-- Ant build script for yfiles -->
  <!-- The java based Ant tool is available from -->
  <!-- http://jakarta.apache.org/ant -->
  <!-- This file demonstrates the use of the yGuard byte -->
  <!-- code obfuscator from yWorks Gmbh -->
  <!-- yGuard can be downloaded from -->
  <!--- http://www.yworks.com/products/yguard -->

  <project name="project" default="yguard" basedir=".">

    <!-- edit the following lines to your needs -->
    <target name="init">
    <property name="project_name" value="DemoProject"/>
    <property name="srcDir" value="."/>
    <property name="classDir" value="classes"/>
    <property name="jar" value="${project_name}.jar"/>
    <property name="obfjar" value="${project_name}_obf.jar"/>
    <property name="renamelog" value="${project_name}_renamelog.xml"/>
    <property name="shrinklog" value="${project_name}_shrinklog.xml"/>
    <property name="mainclass" value="com.mycompany.myapp.Main"/>
    <mkdir dir="${classDir}" />
    </target>


    <target depends="jar" name="yguard">
      <taskdef name="yguard" classname="com.yworks.yguard.YGuardTask"
      classpath="yguard.jar"/>
      <!-- the following can be adjusted to your needs -->
      <yguard>

        <inoutpair in="${jar}" out="${obfjar}"/>

        <shrink logfile="${shrinklog}">

          <keep>
            <class classes="protected"
            methods="protected" fields="protected">
              <patternset>
                <include name="com.mycompany.publicapi.**.*"/>
                <exclude name="com.mycompany.publicapi.private.*"/>
                <include name="com.mycompany.menu.reflection.**.*"/>
              </patternset>
            </class>
          </keep>
        </shrink>

        <rename mainclass="${mainclass}" logfile="${renamelog}">
          <property name="error-checking" value="pedantic"/>

          <keep>
            <class classes="protected"
            methods="protected" fields="protected">
              <patternset>
                <include name="com.mycompany.publicapi.**.*"/>
                <exclude name="com.mycompany.publicapi.private.*"/>
              </patternset>
            </class>
          </keep>
        </rename>

      </yguard>

    </target>

    <!-- compile -->
    <target name="compile" depends="init">
      <javac srcdir="${srcDir}" includes="com/mycompany/**/*.java"
        destdir="${classDir}">
      </javac>
    </target>

    <!-- create .jar -->
    <target name="jar" depends="compile">
      <jar jarfile="${jar}"
        basedir="${classDir}"
        includes="com/mycompany/**">
        <fileset dir="${srcDir}">
          <include name="com/mycompany/resources/*.properties"/>
        </fileset>
      </jar>
    </target>

    <!-- run project -->
    <target name="run" depends="yguard">
      <java classname="${mainclass}" fork="true">
      <classpath>
        <pathelement location="${obfjar}"/>
      </classpath>
      </java>
    </target>

    <!-- removes all that has been built -->
    <target name="clean" depends="init">
      <delete dir="${classDir}" includeEmptyDirs="true" />
    </target>
  </project>

  <!-- end file build.xml -->

Example 2: A Public API

An alternative yguard section could look like this:

  <yguard>

    <inoutpair in="classes.jar" out="classes_obf.jar"/>
    <inoutpair in="utils.jar" out="utils_obf.jar"/>

    <!-- don't let the obfuscator remove the "Deprecated" -->
    <!-- attributes from the .class file entries -->
    <attribute name="Deprecated"/>

    <shrink
      logfile="shrinklog.xml">
      <keep>
        <class classes="protected"
        methods="protected"
        fields="protected"/>
      </keep>
    </shrink>

    <rename mainclass="com.mycompany.myapp.Main"
      logfile="obflog.xml">
      <keep>
        <class classes="protected"
        methods="protected"
        fields="protected"/>
      </keep>
    </rename>

  </yguard>

This case is especially useful when you want to provide and expose a public API. All the classes, methods and fields, that can be seen in a javadoc generated API will be excluded from the shrinking and renaming tasks. Package friendly and private classes, methods and fields will be shrinked or obfuscated whenever possible.
This example also displays the use of the "attribute" element. In this case it prevents the yguard task from removing the "Deprecated" flag from the entities in the .class files.

Example 3: A Demo Program

  <yguard>

    <inoutpair in="demo.jar" out="demo_obf.jar"/>

    <shrink logfile="shrinklog.xml">

      <keep>

        <!-- main method -->
        <method name="void main(java.lang.String[])" class="com.mycompany.myapp.Main" />

        <!-- needed for reflection -->
        <class name="com.mycompany.myapp.data.DataObject"
        methods="public" fields="none"/>
        <!-- needed for reflection (name only) -->
        <class name="com.mycompany.myapp.data.InnerDataObject"/>
        <!-- needed for serialization -->
        <method name="void writeObject(java.io.ObjectOutputStream)">
          <patternset id="datapatternset">
            <include name="com.mycompany.myapp.data.*"/>
          </patternset>
        </method>
        <method name="void readObject(java.io.ObjectInputStream)">
          <patternset refid="datapatternset"/>
        </method>
        <field name="serialVersionUID">
          <patternset refid="datapatternset"/>
        </field>
      </keep>
    </shrink>

    <rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">

      <property name="language-conformity" value="illegal"/>
      <property name="naming-scheme" value="mix"/>
      <keep>
        <class name="com.mycompany.myapp.data.DataObject"
        methods="public" fields="none"/>
        <class name="com.mycompany.myapp.data.InnerDataObject"/>
        <method name="void writeObject(java.io.ObjectOutputStream)">
          <patternset refid="datapatternset" />
        </method>
        <method name="void readObject(java.io.ObjectInputStream)">
          <patternset refid="datapatternset"/>
        </method>
        <field name="serialVersionUID">
          <patternset refid="datapatternset"/>
        </field>
      </keep>
    </rename>

  </yguard>

This example demonstrates the common use case of a demo program. The keep sections of both the shrink and rename elements contain code entities that will often have to be excluded from the shrinking and renaming process. These are the main code entrypoints (the main method), classes that are loaded per reflection and fields and methods needed for serialization. Note how the same patternsets can be reused using the id and refid attributes.

Example 4: A Program Using an External Library

  <yguard>

    <inoutpair in="mydemo.jar" out="mydemo_obf.jar"/>

    <externalclasses>
      <pathelement location="lib/external.jar"/>
      <pathelement location="lib/additional/classes/"/>
    </externalclasses>

    <shrink logfile="shrinklog.xml">
      <property name="error-checking" value="pedantic"/>
      <keep>
        <method name="void main(java.lang.String[])" class="com.mycompany.myapp.Main" />
        <class classes="public"/>
      </keep>
    </shrink>

    <rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">
      <property name="error-checking" value="pedantic"/>
      <keep>
        <class classes="public"/>
      </keep>
    </rename>

  </yguard>

This example demonstrates full method and field obfuscation for a program, that has external dependencies. The dependencies are specified in the externalclasses element using standard Ant path specification mechanisms. Classes residing in lib/external.jar and underneath the lib/additional/classes/ directory (note the trailing slash), will be used to resolve external dependencies during the obfuscation run. This is necessary if external classes want to access obfuscated classes directly using an externally defined interface or superclass. yGuard automatically detects externally declared methods and prevents renaming and shrinking of these items. As a result, the shrinked and obfuscated jar file can be used together with unmodified versions of external libraries without causing any problems.
This example also demonstrates the use of the error-checking property. In this case the Ant target fails if any problem is detected during the obfuscation run.

Example 5: A Program with .properties Files and Other Resource Files

  <yguard>

    <inoutpair in="myapp.jar" out="myapp_obf.jar"/>

    <shrink logfile="shrinklog.xml">
      <keep>
        <!-- single entrypoint: main method -->
        <method name="void main(java.lang.String[])" class="com.mycompany.myapp.Main" />
      </keep>
    </shrink>

    <rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">

      <adjust replaceContent="true">
        <!-- plain-text class names in the config files will -->
        <!-- be replaced with the obfuscated name versions -->
        <include name="**/*.config"/>
        <include name="com/mycompany/myapp/init/Main.properties"/>
      </adjust>
      <adjust replacePath="false">
        <!-- keep the complete path to the resources, (gifs...) even if -->
        <!-- package com.mycompany.myapp gets obfuscated by name -->
        <include name="com/mycompany/myapp/resources/*"/>
      </adjust>
      <adjust replaceName="true">
        <!-- Replace the .properties files' names with the obfuscated -->
        <!-- versions if the corresponding .class files get obfuscated -->
        <include name="**/*.properties"/>
        </adjust>
    </rename>

  </yguard>

This example, too, demonstrates full method and field obfuscation for a program, that uses .properties files and other resources files. Some configuration files are used that contain fully qualified classnames for plugins that are going to be obfuscated. Therefore yGuard is instructed to automatically replace the plain-text entries in those files with the obfuscated name versions.
Additionally some resources are hardcoded into the classes (image locations and html files, e.g.). yGuard gets instructed not to move these resource files even if they reside in a package structure that is obfuscated.
Since the property files have been created with the same name as the classes that make use of them and they are being loaded using this.getClass().getName(), yGuard is configured to rename the .properties files according to the obfuscated names of the corresponding .class files.

Example 6: A Program Linked Against a Library That Needs to be Obfuscated

  <yguard>

    <inoutpair in="myapp.jar" out="myapp_obf.jar"/>
    <inoutpair in="lib/thirdpartylib.jar" out="lib/thirdpartylib_obf.jar"/>

    <externalclasses>
      <pathelement location="lib/external.jar"/>
    </externalclasses>

    <!-- Keep all of the attributes for debugging, e.g. -->
    <attribute name="Deprecated, SourceFile, LineNumberTable, LocalVariableTable>
      <patternset refid="myopenapp"/>
    </attribute>

    <rename mainclass="org.myorg.myapp.Main" logfile="renamelog.xml">

      <property name="error-checking" value="pedantic"/>

      <keep>
      <!-- Tell the obfuscator to only adjust my classes -->
      <!-- to work with the obfuscated 3rd party library -->
      <!-- but leave them virtually unmodified otherwise -->
      <!-- The libconnector package however will be -->
      <!-- obfuscated as much as possible -->
      <class classes="private" methods="private" fields="private">
        <patternset id="myopenapp">
          <include name="org.myorg.myapp.**"/>
          <exclude name="org.myorg.myapp.mylibconnector.**"/>
        </patternset>
      </class>

      </keep>
    </rename>

  </yguard>

This example demonstrates almost no method, class, and field obfuscation for a program, that has external dependencies and additionally depends on a third party library jar which has to be obfuscated before deployment. Only those parts that actually interface with the third party jar in the mylibconnector package are being obfuscated. Nothing in the third party library jar will be exposed in the final application, everything will be obfuscated and the code in the open application that makes use of the third party jar will be adjusted. Note that the public part of the application will still be debuggable since all of the crucial attributes will be exposed for the open application part.
The dependencies are specified in the externalclasses element using standard Ant path specification mechanisms. Classes residing in lib/external.jar will be used to resolve external dependencies during the obfuscation run. This is not strictly necessary in this case since the public API will be fully exposed, i.e. no methods which have been declared by interfaces or super class in external classes will be renamed.

Example 7: Using the extends and implements Attributes (Serializable Exclusion)

  <yguard>

    <inoutpair in="myapp.jar" out="myapp_obf.jar"/>

    <shrink>
      <keep>
        <!-- main method -->
        <method name="void main(java.lang.String[])" class="org.myorg.myapp.Main" />
        <!-- serializable classes -->
        <class implements="java.io.Serializable" classes="private" methods="private" fields="private" />
        <!-- menu items loaded per reflection -->
        <class extends="org.myorg.myapp.MyMenuItem" classes="friendly" methods="public" fields="public" />
      </keep>
    </shrink>

    <rename mainclass="org.myorg.myapp.Main" logfile="renamelog.xml">

      <keep>
        <method name="void readObject(java.io.ObjectInputStream)" />
        <method name="void writeObject(java.io.ObjectOutputStream)" />
        <field name="serialVersionUID" />
        <class extends="org.myorg.myapp.MyMenuItem" classes="friendly" methods="public" fields="public" />
      </keep>
    </rename>

  </yguard>

This example demonstrates the usage of the new implements and extends attributes of the class element. All Serializable classes are excluded from shrinking by using the implements attribute of the class element. Additionally, all classes that extend the base class for menu items, org.myorg.myapp.MyMenuItem, are defined as entrypoints for the shrinking engine using the extends attribute of the class element. The readObject and writeObject methods and the field serialVersionUID needed for serialization are excluded from name obfuscation as well.

Example 8: Annotations in Source Code to Control Obfuscation Exclusion

This section gives examples on how to use annotations to control which elements should be excluded from the obfuscation process (i.e., keep their names). The following assumes that there is an annotation class named com.yworks.util.annotation.Obfuscation in the classpath that follows the convention as described above.

Example 8.a: Obfuscation Exclusion per Item

@com.yworks.util.annotation.Obfuscation( exclude = true, applyToMembers = false)
public class Person {

  public String name;

  public String occupation;

  @com.yworks.util.annotation.Obfuscation( exclude = true )
  public int age;
}

The table above shows the result of the obfuscation of this example. The Person class is annotated to be excluded from the obfuscation, but the applyToMembers attribute is set to false, which means that the child elements of the class (the String and int fields) do not inherit this setting from its parent. The name and occupation fields are not annotated and do not inherit the annotation configuration from their parent, so they are obfuscated. The age field however is also annotated to be excluded from obfuscation and thus keeps its name.

Example 8.b: Obfuscation Exclusion for Members Using applyToMembers

@com.yworks.util.annotation.Obfuscation( exclude = true, applyToMembers = true)
public class Person {

  @com.yworks.util.annotation.Obfuscation( exclude = false )
  public String name;

  public String occupation;

  public int age;
}

Again, the class Person keeps its name, but the configuration is inherited by its members, too. The fields occupation and age have no annotation set and inherit the configuration of its parent, which is exclude = true, so they keep their names. The field name however specifies its own annotation and thus overrides the configuration of its parent and sets its own exclusion to false, so it is obfuscated.

Example 8.c: Obfuscation Exclusion for Members using applyToMembers in the Case of Nested Classes

@Obfuscation ( exclude = true, applyToMembers = true )
public class Person {

  public String name;

  public String occupation;

  public int age;

  @Obfuscation ( exclude = false, applyToMembers = true )
  class BirthInfo {

    String birthPlace;

    class Date {

      int year;

      int month;

      int day;
    }
  }
}

The applyToMembers configuration is also applicable to inner classes: In the above example, the top level class Person is annotated so that itself and all its members should be excluded from obfuscation. But, the inner class BirthInfo overrides this configuration by setting exclude to false for itself and all of its members. When yGuard has to decide whether to keep or obfuscate a non-annotated element, then it will look for annotations by going up the nesting-hierarchy until the top level class is reached or a parent has the applyToMembers configuration set to true. In this case, when deciding whether to keep the inner class Date, yGuard goes up the hierarchy and finds the annotation at BirthInfo, which is annotated exclude = false. This results in Date being obfuscated. The same applies to the members of Date.

Example 8.d: Obfuscation Exclusion Using applyToMembers in the Case of Nested Classes II

@Obfuscation ( exclude = true, applyToMembers = true )
public class Person {

  public String name;

  public String occupation;

  public int age;

  @Obfuscation ( exclude = false, applyToMembers = false )
  class BirthInfo {

    String birthPlace;

    class Date {

      int year;

      int month;

      int day;
    }
  }
}

The above example shows almost the same code as in Example 8.c, but this time the class BirthInfo has the applyToMembers annotation set to false. One might expect that, as a result, all members of BirthInfo are kept and only BirthInfo is obfuscated, but instead, all elements in this example are kept. The explanation: when reaching Date, yGuard is looking up its parent's configuration, BirthInfo, which has applyToMembers = false. yGuard then proceeds to the next parent class in the nesting-hierarchy, Person, which has applyToMembers = true and exclude = true set. This causes Date to be kept. But keeping a class also means that its fully qualified name and thus its nesting-hierarchy needs to be kept. Although the annotation of BirthInfo does not explicitly retain the the name of the class, the retention of Date and its nesting-hierarchy causes BirthInfo to be kept.

Example 8.e: Default Behavior

public class Person {

  public String name;

  public String occupation;

  @com.yworks.util.annotation.Obfuscation
  public int age;

}

This example shows the default behavior of yGuard without specifying an annotation and when not assigning the attributes of the annotation. Person, name and occupation are obfuscated, while age is annotated. The default value for exclude is true, so the field age is not obfuscated.

yGuard provides a simple tool that makes it easy for the obfuscating party to deobfuscate stacktraces which have been obfuscated using yGuard. During the obfuscation yGuard produces an xml logfile which can automatically be gzipped for convenient storage. You should always keep those logfiles in order to be able to deobfuscate fully qualified classnames or methods or fields for debugging purposes e.g.
In order to run the yGuard deobfuscation tool do the following:

      Console> java -jar yguard.jar mylogfile.xml

A tiny GUI will popup that will enable you to easily deobfuscate stacktraces and fully qualified classnames as well as provide a convenient way to browse the mapping generated by yGuard.
In the main window a tree view displays the package, class, and classmember hierarchy using the unobfuscated names. For each entry that has been obfuscated (classes, packages, methods, and fields that have not been obfuscated at all may not always be shown in the tree) the corresponding mapped/obfuscated name is displayed.
The two buttons at the top of the window allow to change the sorting of the items in the tree structure, so that they are either sorted according to their names before or after the obfuscation. Items will always be sorted by type first: packages, classes, innerclasses, methods, and fields. Small icons provide a convenient way to quickly find the corresponding items.

The lower part of the window contains an editable text area that can be used to enter text or paste stacktraces in. Pressing the button at the bottom of the window labelled "Deobfuscate" will trigger the deobfuscation of the contents in the text area. The tool will try to identify fully qualified class names (separated by dots) and use the mapping information to reconstruct the original names. If the tool identifies a stack trace element, it will try to deobfuscate scrambled line numbers, too, if they have been scrambled during the obfuscation process.

If you experience any problems or think you have found a bug feel free to send an email to yguard@yworks.com but please make sure you have read the documentation thoroughly before. We will do our best and try to answer your questions.

The obfuscation and shrinking process can be completely configured inside your Ant script. The yguard task and nested elements should be used according to the following DTD. Note that this is for information purposes only, i.e. you do not have to include the following lines anywhere. This DTD should just provide a quick overview of the yGuard syntax. Due to restrictions of the DTD specification, the given DTD does not describe all available yGuard options. Please browse through the documentation above for complete documentation of the yGuard Ant task elements.

  <!ELEMENT yguard (inoutpair+,externalclasses?,attribute*,(shrink|rename)+)>

  <!ELEMENT inoutpair EMPTY>
  <!ATTLIST inoutpair
  in CDATA #REQUIRED
  out CDATA #REQUIRED
  resources CDATA #IMPLIED>
  <!--
  NOTE: the resources attribute only has an effect if a shrink element is present inside the yguard element.
  -->

  <!ELEMENT externalclasses ANY>
  <!-- the externalclasses element is used just like Ant's classpath
  element. See the Ant documentation for further details-->

  <!ELEMENT attribute (patternset)*>
  name CDATA #REQUIRED>

  <!ELEMENT shrink (entrypointjar*,keep?)>
  <!ATTLIST shrink
  logfile CDATA #IMPLIED
  createStubs CDATA #IMPLIED>

  <!ELEMENT entrypointjar>
  <!ATTLIST entrypointjar
  name CDATA #REQUIRED>

  <!ELEMENT rename (property*,patch?,adjust*,map?,keep?)>
  <!ATTLIST rename
  mainclass CDATA #IMPLIED
  logfile CDATA #IMPLIED
  conservemanifest CDATA #IMPLIED
  replaceClassNameStrings CDATA #IMPLIED>

  <!ELEMENT property EMPTY>
  <!ATTLIST property
  name CDATA #REQUIRED
  value CDATA #REQUIRED>

  <!ELEMENT patch (class)*>

  <!ELEMENT adjust (#PCDATA)>
  <!ATTLIST adjust
  replaceName CDATA #REQUIRED
  replaceContent CDATA #REQUIRED
  replacePath CDATA #REQUIRED>

  <!ELEMENT map (class|method|field|package)*>

  <!ELEMENT package (patternset)*>
  <!ATTLIST package
  name CDATA #REQUIRED
  map CDATA #REQUIRED>
  <!--
  NOTE: the map attribute is only supported
  if the <package> element is nested inside a <map> element, whereas the patternset is
  only supported inside the <keep>/<expose> sections.
  -->

  <!ELEMENT keep (package|class|method|field|sourcefile|linenumbertable)*>
  <!--
  NOTE: the nested <package>,<sourcefile>,<linenumbertable> and <attribute> sections are only
  supported in the <rename> element.
  -->
  <!ATTLIST keep
  linenumbertable CDATA #IMPLIED
  localvariabletable CDATA #IMPLIED
  localvariabletypetable CDATA #IMPLIED
  runtimeinvisibleannotations CDATA #IMPLIED
  runtimeinvisibletypeannotations CDATA #IMPLIED
  runtimevisibleannotations CDATA #IMPLIED
  runtimevisibletypeannotations CDATA #IMPLIED
  sourcefile CDATA #IMPLIED>

  <!ELEMENT class (patternset)*>
  <!ATTLIST class
  classes CDATA #IMPLIED
  fields CDATA #IMPLIED
  map CDATA #IMPLIED
  methods CDATA #IMPLIED
  name CDATA #IMPLIED>
  <!--
  NOTE: the map attribute is only supported
  if the <class> element is nested inside an <rename> element.
  -->

  <!ELEMENT method (patternset)*>
  <!ATTLIST method
  class CDATA #IMPLIED
  map CDATA #IMPLIED
  name CDATA #IMPLIED>
  <!--
  NOTE: the map attribute is only supported
  if the <method> element is nested inside an <rename> element.
  -->

  <!ELEMENT field (patternset)*>
  <!ATTLIST field
  class CDATA #IMPLIED
  map CDATA #IMPLIED
  name CDATA #IMPLIED>
  <!--
  NOTE: the field attribute is only supported
  if the <method> element is nested inside an <rename> element.
  -->

Attention users of IDEs that "support" the creation of Ant files (e.g. IDEA's IntelliJ): Your IDE may indicate some errors inside your ANT file when you use yGuard specific elements. This is because the IDE does not know about the DTD used by yGuard. However this is not a real problem, since the Ant file should nevertheless work as expected.

Copyright © 2002-2014 yWorks. All Rights Reserved.