Page Comparison

Within the OpenMRS Webapp

Everything is delivered from the database in the form of objects: Patient, User, Concept, etc java objects.

...

List<Patient> patients = Context.getPatientService().getAllPatients();
for (Patient patient : patients) {
  System.out.println("Patient: " + patient.getGivenName() + " " + patient.getFamilyName());
}

In an External Application using web services

See Web Services

In an External Application using the API Jar

The openmrs-api-xxx.jar file can be used in stand-alone java applications. There are three simple steps you need to follow:

1. Download/build the openmrs api jar file "openmrs-api.****.jar" and include it on your classpath.
2. Include the dependent libraries on your classpath, which you can get from openmrs-trunk/api/pom.xml.
3. Fire up OpenMRS by calling: Context.startup(<connection.url>, <connection.username>, <connection.password>, getProperties());
4. You need to surround any units of work with Context.openSession() (which startup() calls for you) and Context.closeSession()
5. Authenticate into OpenMRS by calling: Context.authenticate(username, password);
6. You should be able to call into the Context and work with the services.

Example

public static void main(String[] args) {
  File propsFile = new File(OpenmrsUtil.getApplicationDataDirectory(), "openmrs-runtime.properties");**
  Properties props = new Properties();
  OpenmrsUtil.loadProperties(props, propsFile);
  Context.startup("jdbc:mysql://localhost:3306/db-name?autoReconnect=true", "openmrs-db-user", "3jknfjkn33ijt", propsFile);
  try {
    Context.openSession();
    Context.authenticate("admin", "test");
    List<Patient> patients = Context.getPatientService().getPatients("John");
    for (Patient patient : patients) {
      System.out.println("Found patient with name " + patient.getPersonName() + " and uuid: " + patient.getUuid());
    }
    ...
  }
  finally {
    Context.closeSession();
  }
}

• See Overriding OpenMRS Default Runtime Properties for what data you can provide to openmrs

OpenMRS startup environment

In order to start OpenMRS with all it's modules (especially necessary if "mandatory" modules as with OpenMRS 1.6 are present), it is not sufficient to simply include the required jar files. Choose one of the following approaches to get your app started:

...

Note that scheduled tasks can/may/will fail during initialization.

Demarcating start and end of API work

• When coding against the database API, domain objects (Patient, User, etc.) provided from the API are only guaranteed to be valid between calls to context.openSession() and context.closeSession().
  • You needn't worry about this within a web application environment as long as you are using a filter such as org.openmrs.web.OpenmrsFilter (since the filter marks the boundaries around each HTTP request)
  • You cannot use domain objects across transactions (or requests) (e.g., if you loaded a Patient object on one web page, you must reload that object, before using it on subsequent pages)
• It is the developer's responsibility to ensure that context.closeSession() is called (if not within webapp environment) to release precious resources (even in the event of an exception)
• These transaction boundary calls are lightweight -- i.e., there is little penalty for calling them