From 2249c44ff76949d9ccfabfcb21187eadabc62190 Mon Sep 17 00:00:00 2001 From: Sean Leonard Date: Wed, 19 Jun 2013 10:10:19 -0600 Subject: Class and method comments and some readability --- src/se/leap/leapclient/Dashboard.java | 40 ++++++++++++++++- src/se/leap/leapclient/EIP.java | 84 ++++++++++++++++++++++++++++++++--- 2 files changed, 116 insertions(+), 8 deletions(-) (limited to 'src/se/leap') diff --git a/src/se/leap/leapclient/Dashboard.java b/src/se/leap/leapclient/Dashboard.java index d8b3a19..bf754ba 100644 --- a/src/se/leap/leapclient/Dashboard.java +++ b/src/se/leap/leapclient/Dashboard.java @@ -34,6 +34,12 @@ import android.widget.Switch; import android.widget.TextView; import android.widget.Toast; +/** + * The main user facing Activity of LEAP Android, consisting of status, controls, + * and access to preferences. + * + * @author Sean Leonard + */ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterface,Receiver,StateListener { protected static final int CONFIGURE_LEAP = 0; @@ -98,6 +104,10 @@ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterf } } + /** + * Dialog shown when encountering a configuration error. Such errors require + * reconfiguring LEAP or aborting the application. + */ private void configErrorDialog() { AlertDialog.Builder alertBuilder = new AlertDialog.Builder(getAppContext()); alertBuilder.setTitle(getResources().getString(R.string.setup_error_title)); @@ -120,6 +130,10 @@ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterf }); } + /** + * Inflates permanent UI elements of the View and contains logic for what + * service dependent UI elements to include. + */ private void buildDashboard() { provider = Provider.getInstance(); provider.init( this ); @@ -136,6 +150,9 @@ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterf } } + /** + * Builds the UI for the EIP service Dashboard component + */ private void serviceItemEIP() { mEIPReceiver = new EIPReceiver(new Handler()); mEIPReceiver.setReceiver(this); @@ -177,6 +194,12 @@ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterf }); } + /** + * Expands the EIP Dashboard component for extra details view. + * Called by onClick property in client_dashboard.xml layout. + * + * @param view (Unused) The View calling this method by its onClick property + */ public void toggleEipOverview(View view) { if (eipDetail.isShown()) eipDetail.setVisibility(View.GONE); @@ -184,6 +207,11 @@ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterf eipDetail.setVisibility(View.VISIBLE); } + /** + * Launches the se.leap.openvpn.LogWindow Activity showing detailed OpenVPN log + * + * @param view (Unused) The View calling this method by its onClick property + */ public void showEIPLog(View view){ Intent intent = new Intent(getBaseContext(),LogWindow.class); intent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT); @@ -357,7 +385,12 @@ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterf } } - // Used for getting Context when outside of a class extending Context + /** + * For retrieving the base application Context in classes that don't extend + * Android's Activity class + * + * @return Application Context as defined by this for Dashboard instance + */ public static Context getAppContext() { return app; } @@ -380,6 +413,11 @@ public class Dashboard extends Activity implements LogInDialog.LogInDialogInterf }); } + /** + * Inner class for handling messages related to EIP status and control requests + * + * @author Sean Leonard + */ protected class EIPReceiver extends ResultReceiver { Dashboard mDashboard; diff --git a/src/se/leap/leapclient/EIP.java b/src/se/leap/leapclient/EIP.java index cadb449..426f435 100644 --- a/src/se/leap/leapclient/EIP.java +++ b/src/se/leap/leapclient/EIP.java @@ -31,8 +31,13 @@ import android.os.ResultReceiver; import android.util.Log; /** + * EIP is the abstract base class for interacting with and managing the Encrypted + * Internet Proxy connection. Connections are started, stopped, and queried through + * this IntentService. + * Contains logic for parsing eip-service.json from the provider, configuring and selecting + * gateways, and controlling {@link .openvpn.OpenVpnService} connections. + * * @author Sean Leonard - * */ public final class EIP extends IntentService { @@ -96,6 +101,10 @@ public final class EIP extends IntentService { this.stopEIP(); } + /** + * Sends an Intent to bind OpenVpnService. + * Used when OpenVpnService isn't bound but might be running. + */ private void retreiveVpnService() { Intent bindIntent = new Intent(this,OpenVpnService.class); bindIntent.setAction(OpenVpnService.RETRIEVE_SERVICE); @@ -143,6 +152,15 @@ public final class EIP extends IntentService { }; + /** + * Attempts to determine if OpenVpnService has an established VPN connection + * through the bound ServiceConnection. If there is no bound service, this + * method will attempt to bind a running OpenVpnService and send + * Activity.RESULT_CANCELED to the ResultReceiver that made the + * request. + * Note: If the request to bind OpenVpnService is successful, the ResultReceiver + * will be notified in {@link onServiceConnected()} + */ private void isRunning() { Bundle resultData = new Bundle(); resultData.putString(ConfigHelper.REQUEST_TAG, ACTION_IS_EIP_RUNNING); @@ -159,6 +177,10 @@ public final class EIP extends IntentService { } } + /** + * Initiates an EIP connection by selecting a gateway and preparing and sending an + * Intent to {@link se.leap.openvpn.LaunchVPN} + */ private void startEIP() { if (activeGateway==null) activeGateway = selectGateway(); @@ -173,6 +195,10 @@ public final class EIP extends IntentService { mPending = ACTION_START_EIP; } + /** + * Disconnects the EIP connection gracefully through the bound service or forcefully + * if there is no bound service. Sends a message to the requesting ResultReceiver. + */ private void stopEIP() { if (mBound) mVpnService.onRevoke(); @@ -186,6 +212,11 @@ public final class EIP extends IntentService { } } + /** + * Loads eip-service.json from SharedPreferences and calls {@link updateGateways()} + * to parse gateway definitions. + * TODO Implement API call to refresh eip-service.json from the provider + */ private void updateEIPService() { try { eipDefinition = ConfigHelper.getJsonFromSharedPref(ConfigHelper.EIP_SERVICE_KEY); @@ -196,12 +227,23 @@ public final class EIP extends IntentService { updateGateways(); } + /** + * Choose a gateway to connect to based on timezone from system locale data + * + * @return The gateway to connect to + */ private OVPNGateway selectGateway() { // TODO Implement gateway selection logic based on TZ or preferences - // TODO will also remove "first" from OVPNGateway constructor + // TODO Implement search through gateways loaded from SharedPreferences + // TODO Remove String arg constructor in favor of findGatewayByName(String) return new OVPNGateway("first"); } + /** + * Walk the list of gateways defined in eip-service.json and parse them into + * OVPNGateway objects. + * TODO Store the OVPNGateways (as Serializable) in SharedPreferences + */ private void updateGateways(){ JSONArray gatewaysDefined = null; @@ -234,6 +276,13 @@ public final class EIP extends IntentService { } } + /** + * OVPNGateway provides objects defining gateways and their options and metadata. + * Each instance contains a VpnProfile for OpenVPN specific data and member + * variables describing capabilities and location + * + * @author Sean Leonard + */ private class OVPNGateway { private String TAG = "OVPNGateway"; @@ -243,13 +292,17 @@ public final class EIP extends IntentService { private HashMap>> options = new HashMap>>(); - // Constructor to load a gateway by name + /** + * Attempts to retrieve a VpnProfile by name and build an OVPNGateway around it. + * FIXME This needs to become a findGatewayByName() method + * + * @param name The hostname of the gateway to inflate + */ private OVPNGateway(String name){ ProfileManager vpl = ProfileManager.getInstance(context); try { - // TODO when implementing gateway selection logic if ( name == "first" ) { name = vpl.getProfiles().iterator().next().mName; } @@ -264,6 +317,12 @@ public final class EIP extends IntentService { } } + /** + * Build a gateway object from a JSON OpenVPN gateway definition in eip-service.json + * and create a VpnProfile belonging to it. + * + * @param gateway The JSON OpenVPN gateway definition to parse + */ protected OVPNGateway(JSONObject gateway){ mGateway = gateway; @@ -290,13 +349,18 @@ public final class EIP extends IntentService { vpl.saveProfileList(context); } - private void setUniqueProfileName(ProfileManager vpl) { + /** + * Attempts to create a unique profile name from the hostname of the gateway + * + * @param profileManager + */ + private void setUniqueProfileName(ProfileManager profileManager) { int i=0; String newname; try { newname = mGateway.getString("host"); - while(vpl.getProfileByName(newname)!=null) { + while(profileManager.getProfileByName(newname)!=null) { i++; if(i==1) newname = getString(R.string.converted_profile); @@ -312,6 +376,9 @@ public final class EIP extends IntentService { } } + /** + * FIXME This method is really the outline of the refactoring needed in se.leap.openvpn.ConfigParser + */ private void parseOptions(){ // FIXME move these to a common API (& version) definition place, like ProviderAPI or ConfigHelper @@ -393,6 +460,9 @@ public final class EIP extends IntentService { arg.clear(); } + /** + * Create and attach the VpnProfile to our gateway object + */ protected void createVPNProfile(){ try { ConfigParser cp = new ConfigParser(); @@ -401,7 +471,7 @@ public final class EIP extends IntentService { mVpnProfile = vp; Log.v(TAG,"Created VPNProfile"); } catch (ConfigParseError e) { - // FIXME We didn't get a VpnProfile! Error handling! + // FIXME We didn't get a VpnProfile! Error handling! and log level Log.v(TAG,"Error createing VPNProfile"); e.printStackTrace(); } -- cgit v1.2.3