Refactoring Design

This page details the refactoring design that we will implement in the next couple of weeks.

Interfaces (and Helper Classes)

IShell

Status: Implemented

  • void run () : Starts the shell
  • void returnFromActivity (IActivity activity, int returnCode, Hashtable payload) : Return point for activities, which will occur whenever the activity yields control back to the shell, not just when the activity completes.
    • activity is the activity yielding control
    • returnCode attempts to capture the circumstances under which the activity is returning, e.g.:
      • ACTIVITY_CANCEL
      • ACTIVITY_COMPLETE
      • ACTIVITY_CANNOT_LOAD or ACTIVITY_ERROR
      • ACTIVITY_SUSPEND (when launching an unrelated activity, like Settings, on top of the current one)
      • ACTIVITY_NEEDS_RESOLUTION (when launching a related activity on top of the current one, that intends to resolve whatever issue is preventing the current activity from continuing)
    • payload is arbitrary return data that varies by return code. Note: it is not a Context
  • boolean setDisplay (IActivity activity, Displayable d) : When an activity wants to change the display, it should make this request through the shell so that the shell can mediate between multiple activities. If the activity is the currently active one (that is, on screen), the request will almost always be granted.
    • activity is the activity making the request
    • d is the Displayable to show
    • returns whether the request was granted
  • void exit (): Called when the current shell is being destroyed (droos: is this method necessary?)

IActivity

Status: Implemented

None of the following calls are blocking calls.

  • void start (Context c) : called to start the activity the for the first time.
    • c is the Context object, likely a sub-class of Context that contains both the global context and any activity-specific parameters (form ID, patient ID, etc.) the activity needs to run
  • void resume (Context c) : called when the activity is being resumed after it has been suspended (either through halt() or shell.returnFromActivity())
    • c is the Context object which contains global context only; it will not contain the activity-specific parameters that were supplied in the call to start(). Context is passed again because it may have changed since the activity last ran (but it may be the same, as well).
  • void halt (void) : called when the shell is suspending/pre-empting the activity. It is not called when the activity itself causes the suspension (such as calling shell.returnFromActivity())
  • void destroy (void) : called when the shell is terminating the activity and does not plan to re-use the current activity instance
  • void contextChanged (Context c) : called when the global context has changed while the activity is active. Note: this method maybe should come from a separate interface, like ContextListener
    • c is the new Context object that has recently changed. It contains global context only.
  • Context getContext () : Get the activity's current context, including all activity-specific parameters.

WorkflowStack

Status: Implemented

  • Pushes and Pops Modules. Methods are push, size, and pop.

Context

Status: Implemented

  • Methods (Open to Debate)
    • Context(Context context)
    • getCurrentUser()
    • setCurrentUser(String name)
    • setElement(String name, Object value)
    • getListOfElements()
    • removeElement(String name, Object value)
    • clone()
    • mergeInContext(Context context)

Service

  • Methods (Open to Debate)
    • String getServiceID()

IStorageProvider

  • Methods (Open to Debate)
    • String getName()

JavaRosaPlatform

I heard that in Durban, people talked about calling this JavaRosaServiceProvider. I think it's a more descriptive name.

  • Methods (Open to Debate)
    • instance() : Get the singleton
    • getStorageManager() : Deals with PersistentStorage objects (RMS, DataBase, etc)
    • getTransportManager() : Deals with TransportLayer objects (HTTP, SMS, Bluetooth, etc)
    • getPropertyManager() : Registers sets of Properties
    • getExternalDataService () : General services that get data from external sources IE: RFID Reader, Camera, etc.
    • IService getService(String ServiceID) : Place for services we didn't anticipate (also returns the 4 major services above)
    • registerService(IService newService) : Add a new service

RMSUtility

Currently this is the RMSUtility written by Cell Life. I am unclear that we want to enforce the usage of MetaDataObjects at the service-provider level however.

  • Methods (Open to Debate)
    • getName()
    • open()
    • close()
    • writeToRMS(Object, MetaDataObject)
    • updateToRMS(int, Object, MetaDataObject)
    • writeBytesToRMS(byte[], MetaDataObject)
    • deleteRecord(int)
    • delete()
    • retrieveFromRMS(int, Externalizable)
    • retrieveByteDataFromRMS(int)
    • retrieveMetaDataFromRMS(int, Externalizable)
    • getNumberOfRecords()
    • recordAdded(RecordStore, int)
    • recordChanged(RecordStore, int)
    • recordDeleted(RecordStore, int)
    • enumerateMetaData()
    • getNextRecordID()

FormManager Project

We need a place to put all of the activities and components from the old org.javarosa project where they can be used as modules. I propose the following structure Project: Name org.javarosa.formmanager Namespace:

  • org.javarosa.formmanager
    • org.javarosa.formmanager.activity
      • FormListActivity
      • SavedFormsActivity
      • FormViewActivity
    • org.javarosa.formmanager.controller
      • FormController
    • org.javarosa.formmanager.view
      • org.javarosa.formmanager.view.formview
        • FormViewScreen
        • PromptScreen
      • org.javarosa.formmanager.view.chatterbox
        • ChatScreen
        • DisplayFrame
      • SubmitScreen
      • SubmitStatusScreen
    • org.javarosa.formmanager.storage
      • XFormsRMSUtility
      • XFormMetaData
      • ModelRMSUtility
      • ModelMetaData
    • org.javarosa.formmanager.utility
      • various utility classes

XForms Project

The XForms project will be responsible for containing all xforms specific code in JavaRosa. This largely consists of Parsing, but anything including storing or creating properties regarding xforms should end up here.

  • org.javarosa.xform.util
    • JavaRosaXFormsParser
  • org.javarosa.storage.utilities.xform
    • XFormsRMSUtility
  • org.javarosa.model.xform
    • XPathBinding