Adding JavaDoc

Author: MarcMil

soot-infoflow-android/src/soot/jimple/infoflow/android/AndroidLibraryClassPatcher.java

@@ -26,8 +26,10 @@
 import soot.jimple.toolkits.scalar.NopEliminator;
 import soot.util.Chain;
 
-//The generated implementations of this class are semantically equivalent to the AppComponentFactory in Android:
-//https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/core/java/android/app/AppComponentFactory.java
+/**
+ * In addition to the normal JVM library classes, this class also patches
+ * certain Android library classes.
+ */
 public class AndroidLibraryClassPatcher extends LibraryClassPatcher {
 
 	@Override
@@ -37,6 +39,10 @@ public void patchLibraries() {
 		patchComponentFactory();
 	}
 
+	/**
+	 * The generated implementation of this method are semantically equivalent to the AppComponentFactory in Android.
+	 * @see https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/core/java/android/app/AppComponentFactory.java
+	 */
 	protected void patchComponentFactory() {
 		SootClass sc = Scene.v().forceResolve(AndroidEntryPointConstants.APPCOMPONENTFACTORYCLASS,
 				SootClass.SIGNATURES);
@@ -54,6 +60,11 @@ protected void patchComponentFactory() {
 
 	}
 
+	/**
+	 * Patches the instantiate classloader class.
+	 * It returns the default class loader unmodified.
+	 * @param sc the class of the app component factory
+	 */
 	private void patchInstantiateClassLoader(SootClass sc) {
 		SootMethod smInstantiate = getOrCreateMethod(sc,
 				AndroidEntryPointConstants.APPCOMPONENTFACTORY_INSTANTIATECLASSLOADER);
@@ -64,6 +75,12 @@ private void patchInstantiateClassLoader(SootClass sc) {
 
 	}
 
+	/**
+	 * Returns all class names that could be instantiated when
+	 * instantiating a class with the given class name, i.e. all subclasses/implementers.
+	 * @param className the class name (could also represent an interface)
+	 * @return a string array of all possible names.
+	 */
 	protected String[] getAllNames(String className) {
 		List<String> names = new ArrayList<>();
 		SootClass sc = Scene.v().getSootClassUnsafe(className);
@@ -84,6 +101,28 @@ protected String[] getAllNames(String className) {
 		return names.toArray(new String[names.size()]);
 	}
 
+	/**
+	 * Patches an instantiate method. Generates code equivalent to the following:
+	 * 
+	 * <code>
+	 * public void instantiateActivity(ClassLoader cl, String className, Intent intent)
+	 * {
+	 * 
+	 * 	if (className.equals("foo.bar.MainActivity"))
+	 * 		return new foo.bar.MainActivity(); //(1)
+	 * 	if (className.equals("foo.bar.FooActivity"))
+	 * 		return new foo.bar.FooActivity();  //(2)
+	 *  return cl.loadClass(className).newInstance(); //(3)
+	 *  
+	 * }
+	 * </code>
+	 * The instantiation statements (1) and (2) are used to help SPARK and other static algorithms to find
+	 * allocation sites. (3) is the fallback that would normally be the implementation when using Android's default 
+	 * app component factory.
+	 * @param sc the class of the app component factory
+	 * @param subsig the sub signature of the method, in our example case instantiateActivity
+	 * @param names the names for each possible class instantiation, in our example case "foo.bar.MainActivity", "foo.bar.FooActivity"
+	 */
 	protected void patchInstantiate(SootClass sc, String subsig, String... names) {
 
 		if (!sc.isLibraryClass())
@@ -154,6 +193,12 @@ protected void patchInstantiate(SootClass sc, String subsig, String... names) {
 
 	}
 
+	/**
+	 * Creates a method if it doesn't exist. Otherwise, it returns the existing method
+	 * @param sc the class where the method is being looked for
+	 * @param subsig the sub signature of the method
+	 * @return the method
+	 */
 	private static SootMethod getOrCreateMethod(SootClass sc, String subsig) {
 		SootMethod p = sc.getMethodUnsafe(subsig);
 		if (p != null)

soot-infoflow-android/src/soot/jimple/infoflow/android/callbacks/filters/ApplicationCallbackFilter.java

@@ -110,14 +110,14 @@ public boolean accepts(SootClass component, SootMethod callback) {
 			return true;
 
 		String subSig = callback.getSubSignature();
-		String name = callback.getName();
 		final FastHierarchy fh = Scene.v().getOrMakeFastHierarchy();
 		final RefType callbackType = callback.getDeclaringClass().getType();
 		if (AndroidEntryPointConstants.getActivityLifecycleCallbackMethods().contains(subSig))
 			return fh.canStoreType(callbackType, this.activityLifecycleCallbacks);
 		if (AndroidEntryPointConstants.getComponentCallbackMethods().contains(subSig))
 			return fh.canStoreType(callbackType, this.componentCallbacks);
-
+		if (AndroidEntryPointConstants.getComponentCallback2Methods().contains(subSig))
+			return fh.canStoreType(callbackType, this.componentCallbacks2);
 		return true;
 	}
 

soot-infoflow-android/src/soot/jimple/infoflow/android/entryPointCreators/AndroidEntryPointCreator.java

@@ -510,6 +510,10 @@ protected SootMethod createDummyMainInternal() {
 		return mainMethod;
 	}
 
+	/**
+	 * Initializes the methods intended for transferring data (usually intents) between components.
+	 * @param info contains information about the commonly used method names for the interface methods
+	 */
 	private void initializeComponentDataTransferMethods(ComponentExchangeInfo info) {
 
 		for (SootClass s : allComponentClasses) {

soot-infoflow-android/src/soot/jimple/infoflow/android/entryPointCreators/ComponentExchangeInfo.java

@@ -1,8 +1,15 @@
 package soot.jimple.infoflow.android.entryPointCreators;
 
+import java.util.Objects;
+
 import soot.SootClass;
 import soot.SootMethod;
 
+/**
+ * Contains information used for data transfers between arbitrary components.
+ * These components implement common interface methods for setting and retrieving an intent.
+ * In the case of activities, there are also methods to save and retrieve an result intent.
+ */
 public class ComponentExchangeInfo {
 
 	public final SootClass componentDataExchangeInterface;
@@ -11,6 +18,28 @@ public class ComponentExchangeInfo {
 	public final SootMethod getIntentMethod;
 	public final SootMethod setIntentMethod;
 
+	@Override
+	public int hashCode() {
+		return Objects.hash(componentDataExchangeInterface, getIntentMethod, getResultIntentMethod, setIntentMethod,
+				setResultIntentMethod);
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if (this == obj)
+			return true;
+		if (obj == null)
+			return false;
+		if (getClass() != obj.getClass())
+			return false;
+		ComponentExchangeInfo other = (ComponentExchangeInfo) obj;
+		return Objects.equals(componentDataExchangeInterface, other.componentDataExchangeInterface)
+				&& Objects.equals(getIntentMethod, other.getIntentMethod)
+				&& Objects.equals(getResultIntentMethod, other.getResultIntentMethod)
+				&& Objects.equals(setIntentMethod, other.setIntentMethod)
+				&& Objects.equals(setResultIntentMethod, other.setResultIntentMethod);
+	}
+
 	public ComponentExchangeInfo(SootClass componentDataExchangeInterface, SootMethod getIntentMethod,
 			SootMethod setIntentMethod, SootMethod getResultIntentMethod, SootMethod setResultIntentMethod) {
 		this.componentDataExchangeInterface = componentDataExchangeInterface;

soot-infoflow-android/src/soot/jimple/infoflow/android/entryPointCreators/components/AbstractComponentEntryPointCreator.java

@@ -501,6 +501,14 @@ protected void createGetIntentMethod() {
 		b.getUnits().add(Jimple.v().newReturnStmt(lcIntent));
 	}
 
+	/**
+	 * Returns a local that will contain a new instance of a given class using an instantiator/factory.
+	 *  
+	 * @param createdClass the class/type that should be created
+	 * @param creatorMethodSubset the subsignature of the factory class that instantiates the desired instance type
+	 * @param values the values to pass on to the <i>creatorMethodSubset</i> method of the factory class
+	 * @return the local (might be new or reused)
+	 */
 	public Local generateInstantiator(SootClass createdClass, String creatorMethodSubset, Value... values) {
 
 		// If we already have a class local of that type, we re-use it