12009/04/20.
2
3-------
41- Goal
5-------
6
7MkStub is small tool that takes a given JAR and filters all the private stuff we don't want to
8expose, e.g.:
9- remove all private members.
10- only include a subset of classes.
11- exclude specific classes, fields or methods.
12
13Each method body is replaced by the bytecode for 'throw new RuntimeException("stub");'.
14
15
16--------
172- Usage
18--------
19
20To 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
27Signatures 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
33Examples 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
41An 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
47This would include only the indicated package yet would totally exclude the inner class
48and the specific field and the method with the exact given signature.
49
50
51
52To invoke MkStub, the syntax is:
53
54  $ java -jar mkstubs input.jar output.jar [@configfile -pattern +pattern ...]
55
56
57
58--------------------
593- Known Limitations
60--------------------
61
62Most of the following limitations exist solely because of the short development time and
63because the tool was designed to solve one task and not just to be super generic. That means
64any 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--
90end
91