Update Javadocs

hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/entity/EmpiTargetType.java

@@ -1,8 +1,17 @@
 package ca.uhn.fhir.jpa.entity;
 
+/**
+ * Possible legal Empi Target Types, stored in database as ordinals.
+ */
 public enum EmpiTargetType {
+	/**
+	 *
+	 * ORDER MATTERS, IF ADDING NEW VALUES, APPEND ONLY.
+	 */
 	PATIENT,
+
 	PRACTITIONER,
+
 	PERSON;
 
 	EmpiTargetType(){}

hapi-fhir-jpaserver-empi/pom.xml

@@ -19,8 +19,6 @@
 		<dependency>
 			<groupId>ca.uhn.hapi.fhir</groupId>
 			<artifactId>hapi-fhir-server-empi</artifactId>
-
-
 			<version>${project.version}</version>
 		</dependency>
 		<dependency>

hapi-fhir-jpaserver-empi/src/main/java/ca/uhn/fhir/jpa/empi/config/EmpiConsumerConfig.java

@@ -88,6 +88,7 @@ public class EmpiConsumerConfig {
 	EmpiMatchLinkSvc empiMatchLinkSvc() {
 		return new EmpiMatchLinkSvc();
 	}
+
 	@Bean
 	IEmpiBatchService myEmpiBatchService() {
 		return new EmpiBatchSvcImpl();

hapi-fhir-jpaserver-empi/src/main/java/ca/uhn/fhir/jpa/empi/dao/EmpiLinkDaoSvc.java

@@ -113,6 +113,14 @@ public class EmpiLinkDaoSvc {
 		return myEmpiLinkDao.findOne(example);
 	}
 
+	/**
+	 * Given a Target Pid, and a match result, return all links which match these criteria.
+	 *
+	 * @param theTargetPid the target of the relationship.
+	 * @param theMatchResult the Match Result of the relationship
+	 *
+	 * @return a list of {@link EmpiLink} entities matching these criteria.
+	 */
 	public List<EmpiLink> getEmpiLinksByTargetPidAndMatchResult(Long theTargetPid, EmpiMatchResultEnum theMatchResult) {
 		EmpiLink exampleLink = myEmpiLinkFactory.newEmpiLink();
 		exampleLink.setTargetPid(theTargetPid);
@@ -121,6 +129,13 @@ public class EmpiLinkDaoSvc {
 		return myEmpiLinkDao.findAll(example);
 	}
 
+	/**
+	 * Given a target Pid, return its Matched EmpiLink. There can only ever be at most one of these, but its possible
+	 * the target has no matches, and may return an empty optional.
+	 *
+	 * @param theTargetPid The Pid of the target you wish to find the matching link for.
+	 * @return the {@link EmpiLink} that contains the Match information for the target.
+	 */
 	public Optional<EmpiLink> getMatchedLinkForTargetPid(Long theTargetPid) {
 		EmpiLink exampleLink = myEmpiLinkFactory.newEmpiLink();
 		exampleLink.setTargetPid(theTargetPid);
@@ -129,6 +144,13 @@ public class EmpiLinkDaoSvc {
 		return myEmpiLinkDao.findOne(example);
 	}
 
+	/**
+	 * Given an IBaseResource, return its Matched EmpiLink. There can only ever be at most one of these, but its possible
+	 * the target has no matches, and may return an empty optional.
+	 *
+	 * @param theTarget The IBaseResource representing the target you wish to find the matching link for.
+	 * @return the {@link EmpiLink} that contains the Match information for the target.
+	 */
 	public Optional<EmpiLink> getMatchedLinkForTarget(IBaseResource theTarget) {
 		Long pid = myIdHelperService.getPidOrNull(theTarget);
 		if (pid == null) {
@@ -142,6 +164,15 @@ public class EmpiLinkDaoSvc {
 		return myEmpiLinkDao.findOne(example);
 	}
 
+	/**
+	 * Given a person a target and a match result, return the matching EmpiLink, if it exists.
+	 *
+	 * @param thePersonPid The Pid of the Person in the relationship
+	 * @param theTargetPid The Pid of the target in the relationship
+	 * @param theMatchResult The MatchResult you are looking for.
+	 *
+	 * @return an Optional {@link EmpiLink} containing the matched link if it exists.
+	 */
 	public Optional<EmpiLink> getEmpiLinksByPersonPidTargetPidAndMatchResult(Long thePersonPid, Long theTargetPid, EmpiMatchResultEnum theMatchResult) {
 		EmpiLink exampleLink = myEmpiLinkFactory.newEmpiLink();
 		exampleLink.setPersonPid(thePersonPid);
@@ -173,12 +204,25 @@ public class EmpiLinkDaoSvc {
 		return myEmpiLinkDao.findOne(example);
 	}
 
+	/**
+	 * Delete a given EmpiLink. Note that this does not clear out the Person, or the Person's related links.
+	 * It is a simple entity delete.
+	 *
+	 * @param theEmpiLink the EmpiLink to delete.
+	 */
 	@Transactional(propagation = Propagation.REQUIRES_NEW)
 	public void deleteLink(EmpiLink theEmpiLink) {
 		myEmpiLinkDao.delete(theEmpiLink);
 	}
 
-	public List<EmpiLink> findEmpiLinksByPersonId(IBaseResource thePersonResource) {
+	/**
+	 * Given a Person, return all links in which they are the source Person of the {@link EmpiLink}
+	 *
+	 * @param thePersonResource The {@link IBaseResource} Person who's links you would like to retrieve.
+	 *
+	 * @return A list of all {@link EmpiLink} entities in which thePersonResource is the source Person.
+	 */
+	public List<EmpiLink> findEmpiLinksByPerson(IBaseResource thePersonResource) {
 		Long pid = myIdHelperService.getPidOrNull(thePersonResource);
 		if (pid == null) {
 			return Collections.emptyList();
@@ -204,6 +248,14 @@ public class EmpiLinkDaoSvc {
 		return collect;
 	}
 
+	/**
+	 * Given a valid {@link EmpiTargetType}, delete all {@link EmpiLink} entities for that type, and get the Pids
+	 * for the Person resources which were the sources of the links.
+	 *
+	 * @param theTargetType the type of relationship you would like to delete.
+	 *
+	 * @return A list of longs representing the Pids of the Person resources used as the sources of the relationships that were deleted.
+	 */
 	public List<Long> deleteAllEmpiLinksOfTypeAndReturnPersonPids(EmpiTargetType theTargetType) {
 		EmpiLink link = new EmpiLink();
 		link.setEmpiTargetType(theTargetType);
@@ -212,6 +264,13 @@ public class EmpiLinkDaoSvc {
 		return deleteEmpiLinksAndReturnPersonPids(allOfType);
 	}
 
+	/**
+	 * Persist an EmpiLink to the database.
+	 *
+	 * @param theEmpiLink the link to save.
+	 *
+	 * @return the persisted {@link EmpiLink} entity.
+	 */
 	public EmpiLink save(EmpiLink theEmpiLink) {
 		if (theEmpiLink.getCreated() == null) {
 			theEmpiLink.setCreated(new Date());
@@ -220,10 +279,26 @@ public class EmpiLinkDaoSvc {
 		return myEmpiLinkDao.save(theEmpiLink);
 	}
 
+
+	/**
+	 * Given an example {@link EmpiLink}, return all links from the database which match the example.
+	 *
+	 * @param theExampleLink The EmpiLink containing the data we would like to search for.
+	 *
+	 * @return a list of {@link EmpiLink} entities which match the example.
+	 */
    public List<EmpiLink> findEmpiLinkByExample(Example<EmpiLink> theExampleLink) {
 		return myEmpiLinkDao.findAll(theExampleLink);
    }
 
+	/**
+	 * Given a target {@link IBaseResource}, return all {@link EmpiLink} entities in which this target is the target
+	 * of the relationship. This will show you all links for a given Patient/Practitioner.
+	 *
+	 * @param theTargetResource the target resource to find links for.
+	 *
+	 * @return all links for the target.
+	 */
 	public List<EmpiLink> findEmpiLinksByTarget(IBaseResource theTargetResource) {
 		Long pid = myIdHelperService.getPidOrNull(theTargetResource);
 		if (pid == null) {
@@ -234,6 +309,11 @@ public class EmpiLinkDaoSvc {
 		return myEmpiLinkDao.findAll(example);
 	}
 
+	/**
+	 * Factory delegation method, whenever you need a new EmpiLink, use this factory method.
+	 * //TODO Should we make the constructor private for EmpiLink? or work out some way to ensure they can only be instantiated via factory.
+	 * @return A new {@link EmpiLink}.
+	 */
 	public EmpiLink newEmpiLink() {
 		return myEmpiLinkFactory.newEmpiLink();
 	}

hapi-fhir-jpaserver-empi/src/main/java/ca/uhn/fhir/jpa/empi/dao/EmpiLinkFactory.java

@@ -32,6 +32,11 @@ public class EmpiLinkFactory {
 		myEmpiSettings = theEmpiSettings;
 	}
 
+	/**
+	 * Create a new EmpiLink, populating it with the version of the ruleset used to create it.
+	 *
+	 * @return the new {@link EmpiLink}
+	 */
 	public EmpiLink newEmpiLink() {
 		return new EmpiLink(myEmpiSettings.getRuleVersion());
 	}

hapi-fhir-jpaserver-empi/src/main/java/ca/uhn/fhir/jpa/empi/svc/EmpiLinkSvcImpl.java

@@ -107,7 +107,7 @@ public class EmpiLinkSvcImpl implements IEmpiLinkSvc {
 	public void syncEmpiLinksToPersonLinks(IAnyResource thePersonResource, EmpiTransactionContext theEmpiTransactionContext) {
 		int origLinkCount = myPersonHelper.getLinkCount(thePersonResource);
 
-		List<EmpiLink> empiLinks = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(thePersonResource);
+		List<EmpiLink> empiLinks = myEmpiLinkDaoSvc.findEmpiLinksByPerson(thePersonResource);
 
 		List<IBaseBackboneElement> newLinks = empiLinks.stream()
 			.filter(link -> link.isMatch() || link.isPossibleMatch())

hapi-fhir-jpaserver-empi/src/main/java/ca/uhn/fhir/jpa/empi/svc/EmpiPersonMergerSvcImpl.java

@@ -90,8 +90,8 @@ public class EmpiPersonMergerSvcImpl implements IEmpiPersonMergerSvc {
 	}
 
 	private void mergeLinks(IAnyResource theFromPerson, IAnyResource theToPerson, Long theToPersonPid, EmpiTransactionContext theEmpiTransactionContext) {
-		List<EmpiLink> incomingLinks = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(theFromPerson);
+		List<EmpiLink> incomingLinks = myEmpiLinkDaoSvc.findEmpiLinksByPerson(theFromPerson);
-		List<EmpiLink> origLinks = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(theToPerson);
+		List<EmpiLink> origLinks = myEmpiLinkDaoSvc.findEmpiLinksByPerson(theToPerson);
 
 		// For each incomingLink, either ignore it, move it, or replace the original one
 

hapi-fhir-jpaserver-empi/src/test/java/ca/uhn/fhir/jpa/empi/svc/EmpiPersonMergerSvcTest.java

@@ -144,7 +144,7 @@ public class EmpiPersonMergerSvcTest extends BaseEmpiR4Test {
 		createEmpiLink(myFromPerson, myTargetPatient1);
 
 		mergePersons();
-		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(myToPerson);
+		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPerson(myToPerson);
 		assertEquals(1, links.size());
 		assertThat(myToPerson, is(possibleLinkedTo(myTargetPatient1)));
 		assertEquals(1, myToPerson.getLink().size());
@@ -155,7 +155,7 @@ public class EmpiPersonMergerSvcTest extends BaseEmpiR4Test {
 		createEmpiLink(myToPerson, myTargetPatient1);
 
 		mergePersons();
-		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(myToPerson);
+		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPerson(myToPerson);
 		assertEquals(1, links.size());
 		assertThat(myToPerson, is(possibleLinkedTo(myTargetPatient1)));
 		assertEquals(1, myToPerson.getLink().size());
@@ -171,7 +171,7 @@ public class EmpiPersonMergerSvcTest extends BaseEmpiR4Test {
 		createEmpiLink(myToPerson, myTargetPatient1);
 
 		mergePersons();
-		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(myToPerson);
+		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPerson(myToPerson);
 		assertEquals(1, links.size());
 		assertEquals(EmpiLinkSourceEnum.MANUAL, links.get(0).getLinkSource());
 	}
@@ -187,7 +187,7 @@ public class EmpiPersonMergerSvcTest extends BaseEmpiR4Test {
 		createEmpiLink(myToPerson, myTargetPatient1);
 
 		mergePersons();
-		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(myToPerson);
+		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPerson(myToPerson);
 		assertEquals(1, links.size());
 		assertEquals(EmpiLinkSourceEnum.MANUAL, links.get(0).getLinkSource());
 	}
@@ -202,7 +202,7 @@ public class EmpiPersonMergerSvcTest extends BaseEmpiR4Test {
 		saveLink(toLink);
 
 		mergePersons();
-		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPersonId(myToPerson);
+		List<EmpiLink> links = myEmpiLinkDaoSvc.findEmpiLinksByPerson(myToPerson);
 		assertEquals(1, links.size());
 		assertEquals(EmpiLinkSourceEnum.MANUAL, links.get(0).getLinkSource());
 	}