2009/04/20.

---

1- Goal

MkStub is small tool that takes a given JAR and filters all the private stuff we don't want to expose, e.g.:

• remove all private members.
• only include a subset of classes.
• exclude specific classes, fields or methods.

Each method body is replaced by the bytecode for 'throw new RuntimeException("stub");'.

---

2- Usage

To control it, you give it patterns like this:

+foo => accepts all items which signature is exactly "foo" +foo* => accepts all items which signature starts by "foo" -bar => rejects all items which signature is exactly "bar" -bar* => rejects all items which signature starts by "bar"

Signatures are defined by:

• a package name, e.g. com.android.blah
• a dot followed by a class name
• a # followed by a field or method name
• an internal "Java method signature" that define parameters types and return value.

Examples of signatures: com.android.blah com.android.blah.MyClass com.android.blah.MyClass$MyInnerClass com.android.blah.MyClass#mPrivateField com.android.blah.MyClass#getInternalStuff com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V

An example of configuration file: +com.android.blah -com.android.blah.MyClass$MyInnerClass -com.android.blah.MyClass#mPrivateField -com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V

This would include only the indicated package yet would totally exclude the inner class and the specific field and the method with the exact given signature.

To invoke MkStub, the syntax is:

$ java -jar mkstubs input.jar output.jar [@configfile -pattern +pattern ...]

---

3- Known Limitations

Most of the following limitations exist solely because of the short development time and because the tool was designed to solve one task and not just to be super generic. That means any limitation here can be easily lifted.

• The generated constructors are not proper. They do not invoke the matching super() before the generated throw exception. Any attempt to load such a class should trigger an error from the byte code verifier or the class loader.

• We do not currently check whether a class or method uses only included types. Suggestion: if type x.y.z is excluded, then any field, annotation, generic type, method parameter or return value that uses that type should generate a fatal error.

• We do not filter out private classes. Their .class will still be present in the output (and stubbed), unless they are explicitly excluded. This is not orthogonal to the fact that private fields and methods are automatically excluded.

• Private fields and methods are automatically excluded. There is no command line switch to prevent that.

• The stubbed source is always generated. For example if the output jar name is given as ~/somedir/myfinal.jar, there will be a directory created at ~/somedir/myfinal.jar_sources that will contain the equivalent Java sources. There is not command line switch to prevent that.

• There is no attempt to match features or behavior with DroidDoc.

-- end