We should have a common template for all services in our API. This allows for easier comprehension and a cleaner code base overall.
All Services should contain:
Transactions
- The @Transactional annotation should be at the top of the service interface
- Methods that don't write data should also put before their methods
Code Block @Transactional( readOnly = true)
Authentication
- Each method in the interface should have an @Authorized annotation on it
...
- Data should have these privileges (users, encounters, orders):
- PRIV_ADD_THINGS
- PRIV_EDIT_THINGS
- PRIV_VIEW_THINGS
- PRIV_DELETE_THINGS
- PRIV_PURGE_THINGS
- Metadata should have these privileges (encounterType, concepts, program, location):
- PRIV_MANAGE_THING_TYPES (covers add/edit/delete)
- PRIV_VIEW_THING_TYPES
- PRIV_PURGE_THING_TYPES
Parent classes
- All service interfaces should extend org.openmrs.api.OpenmrsService
- All service implementation classes should extend org.openmrs.api.BaseOpenmrsService
Commenting
| Tip |
|---|
In Eclipse, Alt-Shift-J is your friend...or Alt-Command-J on a Mac. |
- Service interface:
- Should have class level comment explaining a typical use case
- Each method should have comment about what it does, each parameter explained, and return value explained
- Deprecated methods should be marked in the javadoc and given a comment about why and what replaces it.
- Service implementation:
- The class comment on the should explain and point back at the interface
- Each method should simply point at the interface
- DAO interface
- Should have class level comment should point back at the interface
- Each method comment should simply point at the interface
- DAO implementation
- Class level comment should point at DAO and service interface
- Each method should point at service interface (and DAO?)
General
- Enumerations should be used instead of numerical constants
Retired vs Voided
- DATA is defined as what is contained in the database as patient information or user defined explanation of metadata
- META DATA is defined as those tables that describe how to store and what is the DATA
- Data should be voided. Meta data should be retired
Data | Meta Data |
|---|---|
|
|
Thing Service
| Code Block |
|---|
@Transactional
public interface ThingService extends OpenmrsService {
/**
* @see #saveThing(Thing)
* @deprecated replaced by saveThing(Thing)
*/
@Authorized({OpenmrsConstants.PRIV_CREATE_THINGS})
public void createThing(Thing thing) throws APIException;
/**
* Gets a Thing by identifier
* @param thindId identifier of desired Thing
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public Thing getThing(Integer thingId) throws APIException;
/**
* Get a Thing by name
* @param thingName is the exact name of the desired Thing
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public Thing getThing(String thingName) throws APIException; // if this is meaningful
/**
* Get a Thing by GUID
* @param guid is the guid of the desired Thing
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public Thing getThingByGuid(String guid) throws APIException; // add this later for sync
/**
* Gets all Things, [including retired|not including voided]
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public List<Thing> getAllThings() throws APIException; // includes retired, but not voided
/**
* Gets all Things
* @param include[Retired|Voided] whether or not to include [retired|voided] Things
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public List<Thing> getAllThings(boolean includeRetired) throws APIException; // only one of these
public List<Thing> getAllThings(boolean includeVoided) throws APIException; // only one of these
/**
* Find Things
* @param query partial name
* @returns matching Things
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public List<Thing> getThings(String query);
/**
* Get Things that match the given properties
* @param ...
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public List<Thing> getThings( ... all properties ... ) throws APIException;
/**
* Get Things by XXX
* @param xxx
*/
@Authorized({OpenmrsConstants.PRIV_VIEW_THINGS})
public List<Thing> getThingsByXXX(XXX xxx) throws APIException; // where XXX is metadata
// in most instances, will delegate to getThings(...all properties...)
/**
* @see #saveThing(Thing)
* @deprecated replaced by saveThing(Thing)
**/
@Authorized({OpenmrsConstants.PRIV_EDIT_THINGS})
public void updateThing(Thing thing) throws APIException;
/**
* Save Thing in database
* @param thing Thing to be saved
*/
@Authorized({OpenmrsConstants.PRIV_EDIT_THINGS})
public Thing saveThing(Thing thing) throws APIException;
/**
* [Retires|Voids] Thing
* @param thing Thing to be [retired|voided]
*/
@Authorized({OpenmrsConstants.PRIV_EDIT_THINGS})
public Thing retireThing(Thing thing) throws APIException; // for metadata, retired returned in getAll
public Thing voidThing(Thing thing) throws APIException; // for data, voided not returned in getAll
/**
* [Unretired|Unvoid] Thing
* @param thing to be recovered
*/
@Authorized({OpenmrsConstants.PRIV_EDIT_THINGS})
public Thing unretireThing(Thing thing) throws APIException; // for metadata
public Thing unvoidThing(Thing thing) throws APIException; // for data
/**
* Remove Thing completely (not reversible)
* @param thing Thing to be purged from the database
*/
@Authorized({OpenmrsConstants.PRIV_PURGE_THINGS})
public Thing purgeThing(Thing thing) throws APIException;
/**
* Remove Thing completely (not reversible)
* @param thing Thing to be purged from the database
* @param cascase if <code>true</code>, related data are purged as well
*/
@Authorized({OpenmrsConstants.PRIV_PURGE_THINGS})
public Thing purgeThing(Thing thing, boolean cascade) throws APIException;
/**
* Remove Thing completely (not reversible)
* @param thing Thing to be purged from the database
* @deprecated use #purgeThing(Thing)
*/
@Authorized({OpenmrsConstants.PRIV_PURGE_THINGS})
public void deleteThing(Thing thing) throws APIException;
|