[Gnumed-devel] open-emed report

[syan tan]

I thought it might be useful to make a report about open-emed project 
structure before I get confused.

The directory structure of open-emeds:
|          the root directory has a build.xml  script, 
|                                                    'ant targets' shows 
the targets,
|                                                    'ant dist' builds 
the distribution directory from the src directory.
|--src
|    |-servers
|    |      |-persistent
|    |           |-gov/lanl/Pids   this contains all the java source 
files relating to the PidsServer.
|    |                                       The entry point is 
IdentityComponentImpl.java ,
|    |                                                                   
            it has  references for identify_person(), and profile_access()
|    |                                             which goes to 
IdentifyPersonImpl.java for the find Person use case,
|    |                                             
ProfileAccessImpl.java for traits retrieval and update when a person is 
selected or edited,
|    |                                             or IdMgrImpl.java  
for identity with traits and identity.id retrieval ( 
find_or_register_ids() ).
|    |       
|    |-clients
|           |--gov/lanl/Pids   this contains the client application for 
the PidServer.
|           |                                 - PidsClientPanel.java , 
TraitsTable.java , and AddEditTraitsFrame.java are where the action is.
|           |             
|           |- webapps - this is new stuff I think.
|                     
|--build  - I ignored this.
|--dist
   |--servers                        - this is where the ant build.xml 
script can run 'ant nameservice' and 'ant pids'
   |        |-pids                  - this is where configuration files 
are. Also a log4j.properties file for setting log levels.
   |            |                         The runtime pids.ior file is 
here too.
   |            |
   |            |-ojb/config     - this is where the apache ojb 
configuration files are.
   |  
   |-client                       -this is where the log4j.properties 
are , and where 'ant pidsclient' will run the client
         |-PIDS                 -this is where the configuration files 
for the client is.

The Server object model for Pids:

The   PidServer is registered under the name "Pilot" with the 
NameService ( 'us/nm/state/doh/Pilot'  actually, but that means there are
5 naming contexts including 'NameService' to traverse to the 'Pilot' 
object ).

This is an IdentityComponent  object,  which implements the idl interface in
       src/interfaces/corbamed/idl/PersonIdService.idl 
; it functions  like a directory as well, and returns handles to the 
following components:

    [java]   identify_person: interface defined   *
    [java]   profile_access: interface defined      *
    [java]   sequential_access: interface defined
    [java]   identity_access: interface defined
    [java]   id_mgr: interface defined                 *
    [java]   correlation_mgr: 2003-12-22 11:34:57,481 [main] DEBUG 
gov.lanl.PidServer.IdentificationComponentImpl  - correlation_mgr() 
CorrelationMgr access method called
    [java] interface defined
    [java]
    [java]   naming_context: interface NOT defined
    [java]   trader_components: interface NOT defined

The ones with the * I've seen being used so far.





Walkthrough of usage (unix):
Build:  ( in the base directory)
   ant dist
run : 
  run pids server:
            cd dist/servers ; ant nameservice; ant pids
  run client (in another xterm):
            cd dist/clients ; ant pidsclient

Call sequences - 

1.   pids server startup :

- loads example identities from file into database. binds to nameservice 
under then name 'us/nm/state/doh/Pilot' ,
which is specified in the config file  dist/servers/pids/server.cfg  , 
property serverName.  The property DBMgr tells TraitFactory what
kind of  persistent delegates for Trait and Identity  to use,  ( 
gov.lanl.Pids.PTrait_ and gov.lanl.Pids.PServer_)  , and also constructs
the static object instance of DBMgrFactory.current() to be the 
OJBDatabaseMgr implementation of DatabaseMgr. The persistent
delegates (PTrait_ and PIdentity_ ) use DBMgrFactory.current() to get 
whatever implementation of DatabaseMgr is in use.
DatabaseMgr has the familiar CRUD (create update delete and retrieve) 
as well as transaction  begin, commit and abort.
The config file  dist/servers/pids/server.cfg also has a property 
"Database=..." which specifies the postgres / mysql /hsqldb   specific
xml config file to make the OJBDatabaseMgr work with your chosen backend.



2.  user presses add Patient,  enters demographics , and presses save:
 AddEditTraitsFrame's actionListener actionPerformed() directs to 
savePatientData().
  This is a C/C++ cum java method which basically does a lot of 
translating of the fields into HL7 version2.3  type format:
i.e.  attributes with names, and values,  names of format 'HL7/xxxxx' ( 
e.g. xxxx = 'PATIENT_NAME', 'PATIENT_ADDRESS', 'SEX' :
the corbamed.jar can be browsed within the an ide to have a look, or do: 
 jar -tvf ./dist/lib/corbamed.jar from the basedirectory | grep HL7).
It then calls
   IdMgr.find_or_register_ids( Trait[][] anArrayOfArraysOfTraits),
each Trait array being the traits of one patient,  without the id, but 
there is only one patient in this case.  The return value is an array of 
new ids.

3. user is editing a Patient; this is the same as 2,
but the dialog has a edit flag set, and  once an array of traits is 
parsed by savePatientData() , it is
put into a ProfileUpdate structure which has a field for id and 
something else ( a empty string array).
This profileUpdate is loaded into an array of that type of 1 element, 
and given to  profile_access.update_and_clear_traits().

4. User enters criteria in the first row of the Client panel, and 
presses find:
 -  self.doFindPatient()  gets an array of TraitSelector objects in the 
form of a Vector from the TraitsTable. getTableSearchTraits().
 - copies the vector into an array,
 - specifies  a  string array of desired trait names, and puts it in a 
SpecifiedTraits object

 -  finds the IdentityComponent object, then finds a IdentifyPersonImpl 
object.
 - calls IdentifyPerson.find_candidates( 
                       selectionTraits,  acceptableTraitStates, 
confidenceLevel,
                       specifiedTraitsToRetrieve, 
                       returnTraitSequenceHolder, 
returnTraitIteratorHolder)
 -  then unloads the trait sequence, and trait iterator of the 
Candidate objects which have id and trait profile.
 - converts them to TaggedTrait objects ( why ? ),  then fills the 
table with the TaggedTrait objects.

5. User enters a specific id and presses getProfile, or double clicks on 
a table row with an id field.
 -   doGetProfile() is called.
 -  identityComponent.profile_access() returns a ProfileAccess object.
 -  ProfileAccess.get_profile(id, spec_traits )    - spec_traits is the 
same type as the previous SpecifiedTraits object,
and is loaded with a string array of trait names to retrieve. The return 
value is   an array of Traits[] (since the user
already knows the id, a Candidate object isn't needed).

So in summary, 
   1. adding  a patient uses  IdMgr.find_or_register_ids( array of 
trait arrays),
   2. editing a  patient uses 
ProfileAcess.update_and_clear_traits(array of ProfileUpdate(id,traits) 
objects)  , 
   3. finding a patient by traits uses IdentifyPerson.find_candidates(  
selection criteria, specified return trait types, holders for return arrays)
   4. and finding a specific person by id uses 
ProfileAccess.get_profile( id, specified return trait types)



     

    













                  
           

/* File: PersonIdService.idl
#include <orb.idl>
#include "Notification.idl"
 */

#ifndef  _PERSON_ID_SERVICE_IDL_
#define  _PERSON_ID_SERVICE_IDL_
#pragma  prefix "omg.org"

#include "corbamed/idl/AbbreviatedIncludes/NamingAuthority.idl"
#include "corbamed/idl/AbbreviatedIncludes/CosNaming.idl"
#include "corbamed/idl/AbbreviatedIncludes/CosTrading.idl"
#include "corbamed/idl/AbbreviatedIncludes/CosPropertyService.idl"
#include "corbamed/idl/NamingAuthority.idl"

interface Identity;
interface IdentifyPerson;
interface ProfileAccess;
interface SequentialAccess;
interface IdentityAccess;
interface IdMgr;
interface CorrelationMgr;

/* ---------------------------------------------------------------
Common Data Types */

typedef NamingAuthority::AuthorityId DomainName;

typedef sequence <DomainName> DomainNameSeq;

typedef NamingAuthority::LocalName PersonId;

typedef sequence <PersonId> PersonIdSeq;

typedef NamingAuthority::LocalName ConceptCode;

typedef NamingAuthority::AuthorityId CodingScheme;

struct QualifiedCode {
        CodingScheme coding_scheme;
        ConceptCode concept_code;
};

struct QualifiedCodeId {
        QualifiedCode code;
        PersonId id;
};

typedef sequence <QualifiedCodeId> QualifiedCodeIdSeq;

struct QualifiedPersonId {
        /* DomainId domain; */
        DomainName domain;
        PersonId id;
};

typedef sequence <QualifiedPersonId> QualifiedPersonIdSeq;

typedef any QualifiedId;

typedef sequence <QualifiedId> QualifiedIdSeq;

typedef NamingAuthority::QualifiedNameStr TraitName;

typedef sequence <TraitName> TraitNameSeq;

typedef any TraitValue;

struct Trait {
        TraitName name;
        TraitValue value;
};

typedef sequence <Trait> TraitSeq;

typedef TraitSeq Profile;

typedef sequence <Profile> ProfileSeq;

enum IdState {

        UNKNOWN,
        INVALID,
        TEMPORARY,
        PERMANENT,
        DEACTIVATED     
};

typedef sequence <IdState> IdStateSeq;

struct IdInfo {
        PersonId id;
        IdState state;
        PersonId preferred_id;
};

typedef sequence <IdInfo> IdInfoSeq;

/* ---------------------------------------------------------------
Miscellaneous Data Types */

typedef string ComponentVersion;

struct ComponentName {
        NamingAuthority::QualifiedName name;
        ComponentVersion version;
};

struct TraitSpec {
        TraitName trait;
        boolean mandatory;
        boolean read_only;
        boolean searchable;
};

typedef sequence <TraitSpec> TraitSpecSeq;

enum HowManyTraits {

        NO_TRAITS,
        SOME_TRAITS,
        ALL_TRAITS      
};

union SpecifiedTraits switch(HowManyTraits) {
        case SOME_TRAITS: TraitNameSeq traits;
};

struct TaggedProfile {
        PersonId id;
        Profile profile;
};

typedef sequence <TaggedProfile> TaggedProfileSeq;

struct QualifiedTaggedProfile {
        QualifiedPersonId id;
        Profile profile;
};

typedef sequence <QualifiedTaggedProfile> QualifiedTaggedProfileSeq;

struct ProfileUpdate {
        PersonId id;
        TraitNameSeq del_list;
        TraitSeq modify_list;
};

typedef sequence <ProfileUpdate> ProfileUpdateSeq;

struct MergeStruct {
        PersonId id;
        PersonId preferred_id;
};

typedef sequence <MergeStruct> MergeStructSeq;

struct TraitSelector {
        Trait trait;
        float weight;
};

typedef sequence <TraitSelector> TraitSelectorSeq;

struct Candidate {
        PersonId id;
        float confidence;
        Profile profile;
};

typedef sequence <Candidate> CandidateSeq;

interface CandidateIterator {
        /* 
        @roseuid 3EF9C2A1015C */
        unsigned long max_left ();
                
        /* 
        @roseuid 3EF9C2A1015F */
        boolean next_n (
                in unsigned long n,
                out CandidateSeq ids
                );
                
        /* 
        @roseuid 3EF9C2A10163 */
        void destroy ();
                
};

typedef unsigned long Index;

typedef sequence <Index> IndexSeq;

enum ExceptionReason {

        UNKNOWN_TRAITS,
        DUPLICATE_TRAITS,
        WRONG_TRAIT_FORMAT,
        REQUIRED_TRAITS,
        READONLY_TRAITS,
        CANNOT_REMOVE,
        MODIFY_OR_DELETE        
};

struct MultipleFailure {
        Index the_index;
        ExceptionReason reason;
        TraitNameSeq traits;
};

typedef sequence <MultipleFailure> MultipleFailureSeq;

/* ---------------------------------------------------------------
Exceptions */

exception InvalidId {
        IdInfo id_info;
};

exception InvalidIds {
        IdInfoSeq id_info;
};

exception DuplicateIds {
        PersonIdSeq ids;
};

exception UnknownTraits {
        TraitNameSeq traits;
};

exception DuplicateTraits {
        TraitNameSeq traits;
};

exception WrongTraitFormat {
        TraitNameSeq traits;
};

exception InvalidStates {
};

exception TooMany {
        unsigned long estimated_max;
};

exception MultipleTraits {
        MultipleFailureSeq failures;
};

exception ReadOnlyTraits {
        TraitNameSeq traits;
};

exception CannotRemove {
        TraitNameSeq traits;
};

exception ModifyOrDelete {
        MultipleFailureSeq failures;
};

exception NotImplemented {
};

exception InvalidWeight {
};

exception CannotSearchOn {
        TraitNameSeq traits;
};

exception IdsExist {
        IndexSeq indices;
};

exception RequiredTraits {
        TraitNameSeq traits;
};

exception ProfilesExist {
        IndexSeq indices;
};

exception DuplicateProfiles {
        IndexSeq indices;
};

exception DomainsNotKnown {
        DomainNameSeq domain_names;
};

exception IdsNotKnown {
        QualifiedPersonIdSeq ids;
};

typedef sequence <Identity> IdentitySeq;

interface IdentificationComponent {
        readonly attribute DomainName domain_name;
        readonly attribute ComponentName component_name;
        readonly attribute TraitSpecSeq supported_traits;
        readonly attribute IdentifyPerson identify_person;
        readonly attribute ProfileAccess profile_access;
        readonly attribute SequentialAccess sequential_access;
        readonly attribute IdentityAccess identity_access;
        readonly attribute IdMgr id_mgr;
        readonly attribute CorrelationMgr correlation_mgr;
        /* readonly attribute Notification::EventComponent  event_component; */
        
        readonly attribute  naming_context;
        readonly attribute  trader_components;
        
        /* 
        @roseuid 3EF9C2A40164 */
        void get_supported_properties (
                in TraitName name,
                out CosPropertyService::Properties trait_defs
                )               
                raises (UnknownTraits);
                
};

/* ---------------------------------------------------------------
IdentifyPerson */

interface IdentifyPerson : IdentificationComponent {
        /* 
        @roseuid 3EF9C2A401DF */
        void find_candidates (
                in TraitSelectorSeq profile_selector,
                in IdStateSeq states_of_interest,
                in float confidence_threshold,
                in unsigned long sequence_max,
                in unsigned long iterator_max,
                in SpecifiedTraits traits_requested,
                out CandidateSeq returned_sequence,
                out CandidateIterator returned_iterator
                )               
                raises 
(TooMany,UnknownTraits,WrongTraitFormat,CannotSearchOn,DuplicateTraits,InvalidStates,InvalidWeight);
                
};

/* ---------------------------------------------------------------
ProfileAccess */

interface ProfileAccess : IdentificationComponent {
        /* 
        @roseuid 3EF9C2A4023D */
        TraitNameSeq get_traits_known (
                in PersonId id
                )               
                raises (InvalidId);
                
        /* 
        @roseuid 3EF9C2A40241 */
        Profile get_profile (
                in PersonId id,
                in SpecifiedTraits traits_requested
                )               
                raises (InvalidId,UnknownTraits,DuplicateTraits);
                
        /* 
        @roseuid 3EF9C2A40246 */
        TaggedProfileSeq get_profile_list (
                in PersonIdSeq ids,
                in SpecifiedTraits traits_requested
                )               
                raises 
(TooMany,InvalidIds,DuplicateIds,UnknownTraits,DuplicateTraits);
                
        /* 
        @roseuid 3EF9C2A4024B */
        TaggedProfileSeq get_deactivated_profile_list (
                in PersonIdSeq ids,
                in SpecifiedTraits traits_requested
                )               
                raises 
(NotImplemented,InvalidIds,DuplicateIds,UnknownTraits,DuplicateTraits);
                
        /* 
        @roseuid 3EF9C2A40251 */
        void update_and_clear_traits (
                in ProfileUpdateSeq profile_update_spec
                )               
                raises (InvalidIds,DuplicateIds,NotImplemented,MultipleTraits);
                
        /* 
        @roseuid 3EF9C2A40254 */
        IdInfoSeq get_id_info (
                in PersonIdSeq ids
                )               
                raises (TooMany,DuplicateIds);
                
};

/* ---------------------------------------------------------------
SequentialAccess */

interface SequentialAccess : IdentificationComponent {
        /* 
        @roseuid 3EF9C2A402AC */
        unsigned long id_count_per_state (
                in IdStateSeq states_of_interest
                )               
                raises (InvalidStates);
                
        /* 
        @roseuid 3EF9C2A402B0 */
        TaggedProfileSeq get_all_ids_by_state (
                in SpecifiedTraits traits_requested,
                in IdStateSeq states_of_interest
                )               
                raises (TooMany,UnknownTraits,DuplicateTraits,InvalidStates);
                
        /* 
        @roseuid 3EF9C2A402B5 */
        TaggedProfileSeq get_first_ids (
                in unsigned long how_many,
                in IdStateSeq states_of_interest,
                in SpecifiedTraits traits_requested
                )               
                raises (TooMany,UnknownTraits,DuplicateTraits,InvalidStates);
                
        /* 
        @roseuid 3EF9C2A402BC */
        TaggedProfileSeq get_last_ids (
                in unsigned long how_many,
                in IdStateSeq states_of_interest,
                in SpecifiedTraits traits_requested
                )               
                raises (TooMany,UnknownTraits,DuplicateTraits,InvalidStates);
                
        /* 
        @roseuid 3EF9C2A402C2 */
        TaggedProfileSeq get_next_ids (
                in PersonId reference_id,
                in unsigned long how_many,
                in IdStateSeq states_of_interest,
                in SpecifiedTraits traits_requested
                )               
                raises 
(TooMany,InvalidId,UnknownTraits,DuplicateTraits,InvalidStates);
                
        /* 
        @roseuid 3EF9C2A402CA */
        TaggedProfileSeq get_previous_ids (
                in PersonId reference_id,
                in unsigned long how_many,
                in IdStateSeq states_of_interest,
                in SpecifiedTraits traits_requested
                )               
                raises 
(TooMany,InvalidId,UnknownTraits,DuplicateTraits,InvalidStates);
                
};

interface Identity {
        readonly attribute IdentificationComponent source_component;
        readonly attribute IdInfo id_info;
        readonly attribute TraitNameSeq traits_with_values;
        readonly attribute long trait_value_count;
        
        /* 
        @roseuid 3EF9C2A50034 */
        Trait get_trait (
                in TraitName trait_requested
                )               
                raises (UnknownTraits);
                
        /* 
        @roseuid 3EF9C2A50039 */
        Profile get_profile (
                in SpecifiedTraits traits_requested
                )               
                raises (UnknownTraits,DuplicateTraits);
                
        /* 
        @roseuid 3EF9C2A5003E */
        Profile get_deactivated_profile (
                in SpecifiedTraits traits_requested
                )               
                raises (NotImplemented,UnknownTraits,DuplicateTraits);
                
        /* 
        @roseuid 3EF9C2A50043 */
        void update_and_clear_traits (
                in ProfileUpdate profile_update_spec
                )               
                raises 
(NotImplemented,UnknownTraits,WrongTraitFormat,ModifyOrDelete,ReadOnlyTraits,CannotRemove,DuplicateTraits);
                
        /* 
        @roseuid 3EF9C2A50048 */
        void done ();
                
};

/* ---------------------------------------------------------------
IdentityAccess */

interface IdentityAccess : IdentificationComponent {
        /* 
        @roseuid 3EF9C2A40327 */
        Identity get_identity_object (
                in PersonId id
                )               
                raises (InvalidId);
                
        /* 
        @roseuid 3EF9C2A4032B */
        IdentitySeq get_identity_objects (
                in PersonIdSeq ids
                )               
                raises (InvalidIds);
                
};

/* ---------------------------------------------------------------
IdMgr */

interface IdMgr : IdentificationComponent {
        /* 
        @roseuid 3EF9C2A5009E */
        PersonIdSeq register_new_ids (
                in ProfileSeq profiles_to_register
                )               
                raises (ProfilesExist,DuplicateProfiles,MultipleTraits);
                
        /* 
        @roseuid 3EF9C2A500A2 */
        PersonIdSeq find_or_register_ids (
                in ProfileSeq profiles_to_register
                )               
                raises (DuplicateProfiles,MultipleTraits);
                
        /* 
        @roseuid 3EF9C2A500A6 */
        void register_these_ids (
                in TaggedProfileSeq profiles_to_register
                )               
                raises 
(NotImplemented,IdsExist,DuplicateIds,ProfilesExist,DuplicateProfiles,MultipleTraits);
                
        /* 
        @roseuid 3EF9C2A500AA */
        PersonIdSeq create_temporary_ids (
                in ProfileSeq profiles_to_register
                )               
                raises (MultipleTraits);
                
        /* 
        @roseuid 3EF9C2A500AD */
        PersonIdSeq make_ids_permanent (
                in PersonIdSeq ids_to_modify
                )               
                raises (InvalidIds,DuplicateIds,RequiredTraits);
                
        /* 
        @roseuid 3EF9C2A500B1 */
        IdInfoSeq merge_ids (
                in MergeStructSeq ids_to_merge
                )               
                raises (InvalidIds,DuplicateIds);
                
        /* 
        @roseuid 3EF9C2A500B5 */
        IdInfoSeq unmerge_ids (
                in PersonIdSeq ids_to_unmerge
                )               
                raises (InvalidIds,DuplicateIds);
                
        /* 
        @roseuid 3EF9C2A500B8 */
        IdInfoSeq deprecate_ids (
                in PersonIdSeq ids_to_deprecate
                )               
                raises (InvalidIds,DuplicateIds);
                
};

/* ---------------------------------------------------------------
CorrelationMgr */

interface CorrelationMgr : IdentificationComponent {
        readonly attribute DomainNameSeq source_domains;
        
        /* 
        @roseuid 3EF9C2A5015F */
        void load_profiles (
                in QualifiedTaggedProfileSeq tagged_profiles
                )               
                raises (UnknownTraits,WrongTraitFormat,DomainsNotKnown);
                
        /* 
        @roseuid 3EF9C2A50162 */
        QualifiedPersonIdSeq get_corresponding_ids (
                in QualifiedPersonId from_id,
                in DomainNameSeq to_domains
                )               
                raises (DomainsNotKnown,IdsNotKnown);
                
        /* 
        @roseuid 3EF9C2A50167 */
        PersonIdSeq find_or_register_ids (
                in QualifiedTaggedProfileSeq tagged_profiles
                )               
                raises (MultipleTraits,DomainsNotKnown,NotImplemented);
                
};

/* _PERSON_ID_SERVICE_IDL_ */

#endif