1 2009/04/20. 2 3 ------- 4 1- Goal 5 ------- 6 7 MkStub is small tool that takes a given JAR and filters all the private stuff we don't want to 8 expose, e.g.: 9 - remove all private members. 10 - only include a subset of classes. 11 - exclude specific classes, fields or methods. 12 13 Each method body is replaced by the bytecode for 'throw new RuntimeException("stub");'. 14 15 16 -------- 17 2- Usage 18 -------- 19 20 To control it, you give it patterns like this: 21 22 +foo => accepts all items which signature is exactly "foo" 23 +foo* => accepts all items which signature starts by "foo" 24 -bar => rejects all items which signature is exactly "bar" 25 -bar* => rejects all items which signature starts by "bar" 26 27 Signatures are defined by: 28 - a package name, e.g. com.android.blah 29 - a dot followed by a class name 30 - a # followed by a field or method name 31 - an internal "Java method signature" that define parameters types and return value. 32 33 Examples of signatures: 34 com.android.blah 35 com.android.blah.MyClass 36 com.android.blah.MyClass$MyInnerClass 37 com.android.blah.MyClass#mPrivateField 38 com.android.blah.MyClass#getInternalStuff 39 com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V 40 41 An example of configuration file: 42 +com.android.blah 43 -com.android.blah.MyClass$MyInnerClass 44 -com.android.blah.MyClass#mPrivateField 45 -com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V 46 47 This would include only the indicated package yet would totally exclude the inner class 48 and the specific field and the method with the exact given signature. 49 50 51 52 To invoke MkStub, the syntax is: 53 54 $ java -jar mkstubs input.jar output.jar [@configfile -pattern +pattern ...] 55 56 57 58 -------------------- 59 3- Known Limitations 60 -------------------- 61 62 Most of the following limitations exist solely because of the short development time and 63 because the tool was designed to solve one task and not just to be super generic. That means 64 any limitation here can be easily lifted. 65 66 - The generated constructors are not proper. They do not invoke the matching super() 67 before the generated throw exception. Any attempt to load such a class should trigger 68 an error from the byte code verifier or the class loader. 69 70 - We do not currently check whether a class or method uses only included types. 71 Suggestion: if type x.y.z is excluded, then any field, annotation, generic type, 72 method parameter or return value that uses that type should generate a fatal error. 73 74 - We do not filter out private classes. Their .class will still be present in the 75 output (and stubbed), unless they are explicitly excluded. 76 This is not orthogonal to the fact that private fields and methods are automatically 77 excluded. 78 79 - Private fields and methods are automatically excluded. There is no command line 80 switch to prevent that. 81 82 - The stubbed source is always generated. For example if the output jar name is 83 given as ~/somedir/myfinal.jar, there will be a directory created at 84 ~/somedir/myfinal.jar_sources that will contain the equivalent Java sources. 85 There is not command line switch to prevent that. 86 87 - There is no attempt to match features or behavior with DroidDoc. 88 89 -- 90 end 91
