Code samples for the Java SDK – Real Data Digital Pathology blog

Java sample code availability

Three months ago we introduced the SDK for Java.

A set of code samples can come very handy to ease end users’ first interaction with both PMA.Start and its bigger brother PMA.core. A folder named “samples” was added for this purpose to our PMA.java GitHub repository.

Introduction

For the samples we added, we create a Java HTTPServlet class that interacts with the Java SDK to generate HTML code to be displayed on a web browser.
We aim to make the samples as simple & general as possible, end users can then adapt them to their needs depending on what architecture & frameworks they rely on for their Java web application.

PMA.Start

For the following samples to be run successfully, you’ll need to have PMA.Start installed and running on your computer.
For more information about PMA.Start, refer to https://free.pathomation.com
If you don’t have PMA.Start installed yet on your computer, make sure you download it from https://free.pathomation.com/download/ for free.

This first sample checks if PMA.Start (PMA.core.lite) is installed and running on end user’s computer :


package samples_10;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.*;

public class IdentifyingPMAStart extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      // test for PMA.core.lite (PMA.start)
      out.println("Are you running PMA.core.lite? " + (Core.isLite() ? "Yes!" : "no :-(") + "<br />");
      out.println("Seeing 'no' and want to see 'yes'? Make sure PMA.start is running on your system or download it from "
                  + "<a href = \"http://free.pathomation.com\">http://free.pathomation.com</a>");
      out.println("</html>");

   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

If PMA.Start is actually running, it returns :

Version info

The second sample is quite similar to the previous one for it checks if PMA.Start is running, if yes it displays its version number

package samples_20;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;

public class GettingVersionInformationPMAStart extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      // test for PMA.core.lite (PMA.start)
      if (!Core.isLite()) {
         // don't bother running this script if PMA.start isn't active
         out.println("PMA.start is not running. Please start PMA.start first");
      } else {
         // assuming we have PMA.start running; what's the version number?
         out.println("You are running PMA.start version " + Core.getVersionInfo());
      }
      out.println("</html>");
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

Making the connection

For the third sample, a connection is established to PMA.Start to retrieve a sessionID


package samples_30;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;

public class ConnectingToPMAStart extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
         
      ServletOutputStream out = response.getOutputStream();
      String sessionID = Core.connect();
      out.println("<html>");
      if (sessionID == null) {
         out.println("Unable to connect to PMA.start");
      } else {
         out.println("Successfully connected to PMA.start; sessionID = " + sessionID);
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect();
      }
      out.println("</html>");   
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

If the connection succeeds, the sessionID is then displayed on the web browser

Finding your hard disks

For the fourth sample, a connection is established to PMA.Start, then the local HDD is parsed to retrieve root directories (Drive letters) :


package samples_40;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;

public class GettingDriveLettersFromPMAStart extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      // establish a default connection to PMA.start
      if (Core.connect() != null) {
         out.println("The following drives were found on your system:" + "<br/>");
         for (String rootDirectory : Core.getRootDirectories()) {
            out.println(rootDirectory + "<br/>");
         }
         out.println("Can't find all the drives you're expecting? For network-connectivity (e.g. mapped drive access) you need PMA.core instead of PMA.start");
      } else {
         out.println("Unable to find PMA.start");
      }
      out.println("</html>");         
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

If the connection succeeds, a list of drive letters is displayed one by one on the web browser

Navigating directories

The fifth sample is very similar to previous one, it selects the first root directory (drive letter), its content is then displayed one by one


package samples_60;

import java.io.IOException;
import java.util.List;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;

public class GettingDirectoriesPMAStart extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      String sessionID = Core.connect();
      if (sessionID == null) {
         out.println("Unable to connect to PMA.start");
      } else {
         out.println("Successfully connected to PMA.start" + "<br/>");
         List<String> rootDirs = Core.getRootDirectories();
         out.println("Directories found in " + rootDirs.get(0) + ":" + "<br/>");
         List<String> dirs = Core.getDirectories(rootDirs.get(0), sessionID);
         for (String d : dirs) {
            out.println(d + "<br/>");
         }
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect(sessionID);
      }
      out.println("</html>");         
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

Successful connection results in a list of drive letters with their respective folders shown one by one

Looking for slides

For the next sample, a connection is established to PMA.Start, then we look for the first non empty directory inside the local HDD to browse its content


package samples_80;

import java.io.IOException;
import java.util.List;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;

public class GettingSlidesPMAStart extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      String sessionID = Core.connect();
      if (sessionID == null) {
         out.println("Unable to connect to PMA.start");
      } else {
         out.println("Successfully connected to PMA.start" + "<br/>");
         // for this demo, we don't know where we can expect to find actual slides
         // the getFirstNonEmptyDirectory() method wraps around recursive calls to getDirectories() and is useful to "just" find a bunch of slides in "just" any folder
         String dir = Core.getFirstNonEmptyDirectory("/", sessionID);
         out.println("Looking for slides in " + dir + ":" + "<br/>");
         List<String> slides = Core.getSlides(dir, sessionID);
         for (String slide : slides) {
            out.println(slide + "<br/>");
         }
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect(sessionID);
      }
      out.println("</html>");         
      
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

A quite similar result can be obtained if connection succeeds

Listing slides

Last sample for PMA.Start is a continuation for previous one, once the first non empty directory is found, the list of slides within is displayed successively (besides each slide name, its UID is added)


package samples_90;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;

public class GetUIDSlidePMAStart extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      String sessionID = Core.connect();
      if (sessionID == null) {
         out.println("Unable to connect to PMA.start");
      } else {
         out.println("Successfully connected to PMA.start" + "<br/>");
         String dir = Core.getFirstNonEmptyDirectory("/", sessionID);
         out.println("Looking for slides in " + dir + "<br/>");
         for (String slide : Core.getSlides(dir, sessionID)) {
            out.println(slide + " - " + Core.getUid(slide, sessionID) + "<br/>");
         }
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect(sessionID);
      }
      out.println("</html>");      
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

Here is what you can get for a successful connection

PMA.core

One main difference between PMA.Start and PMA.core is the former is run on a server which implies end users connect to through authentication (server URL, username, password).
For better code organisation & readability, we added Config class which intends to provide a single file to define the connection values to interact with PMA.core.
As You can notice later on the samples for PMA.core, HTTPServlet Classes for each sample retrieve connection values from Config class.
End users are invited to substitute the server’s url & credentials with their own respective values!


package configuration;

public class Config {
   
   // modify the following three lines for your specific circumstances:
   public static String pmaCoreServer = "http://my_server/pma.core";
   public static String pmaCoreUser = "user";
   public static String pmaCorePass = "secret";
}

First sample on the list checks if the url provided refers to a PMA.Start instance


package samples_10;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.*;
import Configuration.Config;

public class IdentifyingPMACore extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      String pmaCoreServer = Config.pmaCoreServer;

      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      // testing actual "full" PMA.core instance that may or may not be out there
      out.println("Are you running PMA.start(PMA.core.lite) at " + pmaCoreServer + " ? " + ((Core.isLite(pmaCoreServer) != null && 
            (Core.isLite(pmaCoreServer) == true))  ? "Yes!" : "no :-(") + "<br />");
      out.println(
            "Are you running PMA.start(PMA.core.lite) at http://nowhere ? "
                  + ((Core.isLite("http://nowhere") != null && (Core.isLite("http://nowhere") == true)) ? "Yes!" : "no :-("));
      out.println("</html>");

   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

The second sample retrieves the version info for the provided PMA.core instance, it also shows what you would get trying a “bogus” URL


package samples_20;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;
import Configuration.Config;

public class GettingVersionInformationPMACore extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
         
      String pmaCoreServer = Config.pmaCoreServer;
      
      ServletOutputStream out = response.getOutputStream();
      out.println("<html>");
      out.println("You are running PMA.core version " + Core.getVersionInfo(pmaCoreServer) + " at " + pmaCoreServer + "<br/>");
      
      // what happens when we run it against a bogus URL?
      String version = Core.getVersionInfo("http://nowhere/");
      
      if (version == null) {
         out.println("Unable to detect PMA.core at specified location (http://nowhere/)");
      } else {
         out.println("You are running PMA.core version " + version);
      }
      out.println("</html>");
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

For the third sample a connection is established to the PMA.Core instance, then the sessionID generated is displayed on web browser


package samples_30;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;
import Configuration.Config;

public class ConnectingToPMACore extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
         
      String pmaCoreServer = Config.pmaCoreServer;
      String pmaCoreUser = Config.pmaCoreUser;
      String pmaCorePass = Config.pmaCorePass;
      
      ServletOutputStream out = response.getOutputStream();
      String sessionID = Core.connect(pmaCoreServer, pmaCoreUser, pmaCorePass);
      out.println("<html>");
      if (sessionID == null) {
         out.println("Unable to connect to PMA.core at specified location (" + pmaCoreServer + ")");
      } else {
         out.println("Successfully connected to PMA.core; sessionID = " + sessionID);
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect();
      }
      out.println("</html>");   
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

In analogy to previous PMA.Start samples, The next sample searches for root directories of the provided PMA.core instance and displays them one by one


package samples_40;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;
import Configuration.Config;

public class GettingRootDirectoriesFromPMACore extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      String pmaCoreServer = Config.pmaCoreServer;
      String pmaCoreUser = Config.pmaCoreUser;
      String pmaCorePass = Config.pmaCorePass;
      
      ServletOutputStream out = response.getOutputStream();
      String sessionID = Core.connect(pmaCoreServer, pmaCoreUser, pmaCorePass);
      out.println("<html>");
      if (sessionID == null) {
         out.println("Unable to connect to PMA.core at specified location (" + pmaCoreServer + ")");
      } else {
         out.println("Successfully connected to " + pmaCoreServer + "<br/>");
         out.println("You have the following root-directories at your disposal:" + "<br/>");
         for (String rd : Core.getRootDirectories(sessionID)) {
            out.println(rd + "<br/>");
         }
         Core.disconnect(sessionID);
      }
      out.println("</html>");         
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

The fifth sample on the list is very similar to previous one, except that instead of displaying a complete list of root directories it only displays the first one and browses its content


package samples_60;

import java.io.IOException;
import java.util.List;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;
import Configuration.Config;

public class GettingDirectoriesPMACore extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      String pmaCoreServer = Config.pmaCoreServer;
      String pmaCoreUser = Config.pmaCoreUser;
      String pmaCorePass = Config.pmaCorePass;

      ServletOutputStream out = response.getOutputStream();
      String sessionID = Core.connect(pmaCoreServer, pmaCoreUser, pmaCorePass);
      out.println("<html>");
      if (sessionID == null) {
         out.println("Unable to connect to PMA.core at specified location (" + pmaCoreServer + ")" + "<br/>");
      } else {
         out.println("Successfully connected to PMA.core; sessionID = " + sessionID + "<br/>");
         List<String> rootDirs = Core.getRootDirectories();
         out.println("Directories found in " + rootDirs.get(0) + ":" + "<br/>");
         List<String> dirs = Core.getDirectories(rootDirs.get(0), sessionID);
         for (String d : dirs) {
            out.println(d + "<br/>");
         }
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect(sessionID);
      }
      out.println("</html>");         
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

For the next sample, a connection is established to the provided PMA.core instance.
If Successful, we look for the first non empty directory to display the list of slides within successively


package samples_80;

import java.io.IOException;
import java.util.List;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;
import Configuration.Config;

public class GettingSlidesPMACore extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      String pmaCoreServer = Config.pmaCoreServer;
      String pmaCoreUser = Config.pmaCoreUser;
      String pmaCorePass = Config.pmaCorePass;
      
      ServletOutputStream out = response.getOutputStream();
      String sessionID = Core.connect(pmaCoreServer, pmaCoreUser, pmaCorePass);
      out.println("<html>");
      if (sessionID == null) {
         out.println("Unable to connect to PMA.core at specified location (" + pmaCoreServer + ")" + "<br/>");
      } else {
         out.println("Successfully connected to PMA.core; sessionID = " + sessionID + "<br/>");
         // for this demo, we don't know where we can expect to find actual slides
         // the getFirstNonEmptyDirectory() method wraps around recursive calls to getDirectories() and is useful to "just" find a bunch of slides in "just" any folder
         String dir = Core.getFirstNonEmptyDirectory("/", sessionID);
         out.println("Looking for slides in " + dir + ":" + "<br/>");
         List slides = Core.getSlides(dir, sessionID);
         for (String slide : slides) {
            out.println(slide + "<br/>");
         }
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect(sessionID);
      }
      out.println("</html>");      
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

What we did on previous sample is extended on the last sample on this list, so in addition to displaying slides’ name we add also the UID for each slide


package samples_90;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pathomation.Core;
import Configuration.Config;

public class GetUIDSlidePMACore extends HttpServlet {

   private static final long serialVersionUID = 1L;

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {

      String pmaCoreServer = Config.pmaCoreServer;
      String pmaCoreUser = Config.pmaCoreUser;
      String pmaCorePass = Config.pmaCorePass;
      
      ServletOutputStream out = response.getOutputStream();
      String sessionID = Core.connect(pmaCoreServer, pmaCoreUser, pmaCorePass);
      out.println("<html>");
      if (sessionID == null) {
         out.println("Unable to connect to PMA.core at specified location (" + pmaCoreServer + ")" + "<br/>");
      } else {
         out.println("Successfully connected to PMA.core; sessionID = " + sessionID + "<br/>");
         String dir = Core.getFirstNonEmptyDirectory("/", sessionID);
         out.println("Looking for slides in " + dir + "<br/>");
         for (String slide : Core.getSlides(dir, sessionID)) {
            out.println(slide + " - " + Core.getUid(slide, sessionID) + "<br/>");
         }
         // not always needed; depends on whether the client (e.g. browser) still needs to SessionID as well
         Core.disconnect(sessionID);
      }
      out.println("</html>");      
   }

   @Override
   protected void doPost(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
      this.doGet(request, response);
   }
}

What’s next?

In this blog post we toured you around our PMA.java SDK. We focused on basic back-end interactions like connecting and finding out which slides are available. We showed you how to navigate around our sample files that we now deposit as part our respective github repositories.

We intend to keep building on top of these initial samples. At the time you read this, there may already be more samples available in addition to the ones described here, so make sure to check.

In a next blog post, we intend to provide you with sample code to start building graphical user interfaces for digital pathology using the pathomation.UI namespace (if you just can’t wait; feel free to already read how this is done in PHP).