BioMight Development Guide - SurferJim/BioMight GitHub Wiki
Introduction
BioMight is a Web JEE (Java Enterprise Edition) application that is currently set up to run on the TomEE application server. It uses MySQL as its database and uses a JDBC connection as the data conduit. Below is a typical, but simplified, deployment model that could be used for any Web application. TomEE provides the Application Server and a lightweight JEE Application server under one program.
BioMight’s Java classes mimic biological components. They run in the Web Container (Client Code) that runs on the Application server. These Java class gather data/input from the user via the web page, package it up, and then send it to the EJB component for processing.
The EJB component runs under the JEE Application server and contains the core programming logic that creates the biological components and stores the information in the database. This model allows one to distribute work between the Web Container and the EJB Container.
BioMight Process Model
Below, we show the Java projects, or libraries that comprise the application. There are 4 projects. The BioMightWeb project contains the Java client classes such as Arm, Leg, Stomach, Cell, DNA, etc. These classes define the starting coordinates for the biological component and attributes such as color, shape, texture that are gathered from the user via the web pages. This provides the capability to set the values for the component properties providing a way for the BioMight engine to generate uniqueness.
The BioMightEJBClient contains the glue that allows the client code to talk with the code on the JEE Application Server. It contains declarations for each method that exists in the corresponding EJBs. It is a way to present a listing of what’s available.
The BioMightUtility project has methods that are used by the Web and EJB projects such as drawing graphics, and defining common data objects that are used to pass information between the two application layers. As one is aware, these objects are Serializable as they are transmitted across the network. Lastly, the BioMightEJB project which contains the code to create the 3D objects by generating and persisting the datapoints to the database.
Below is a snapshot view of how the projects are organized in the Eclipse IDE;
Parent-Child Hierarchy
BioMight organizes its components into parent-child hierarchial relationship. For instance, in the Body view, the Body Java class sits at the top, with Head, Neck, Chest, and Stomach as child objects, as the Head Java class has child objects such as Eyes, Ears, Nose, Eyebrow, Hair, etc.
In this hierarchy there are also pairs. For instance, most humans have a pair of arms and legs, and a multitude of thoracic vertebrae. When there is one instance of an object, that object does all the needed work, for example, retrieving and writing the data for the object to/from the database. Where there is a pair, or a collection of objects, the collection class gets the data and then calls upon the Java object to be created using that data.
There are just over five-thousand Java client-based classes in the BioMightWeb library. Fortunately, they all work the same. Each has a set of methods; constructors(), create(), generate(), getX3D() and an execute() .
All Java classes in the Web Client library contain a call to the getComponents() method that is contained in the BioMightBean EJB. This method gets the data from the database that it uses to construct itself, based on its peroperties, as well as data for its X3D representation.
All Web Client classes also have a generate() method. This calls upon the associated generateXXXX() method that resides in one of the EJB Java objects (Server Code) that run in the EJB container such as the BioMightVascularBean, BioMightSkeletalBean, or the BioMightMuscularBean.
BioMight WebClient Content
In the screen capture below, we see how the WebContent portion of the WebClient is organized.
The **images ** folder contains buttons, and icons that are used in the BioMight apps, and appear in the Web Browser as the user views a web page. We see that Login.jsp page is highlighted. This is the entry point into the application and where one's session object is established for the conversational exchange. The BioMightPalette is where one assembles components into a 3D animation, while the BioMightView page is the central page for navigating through, and viewing, and manipulating the models.
BioMight WebClient Code
The WebClient contains an abundance of Java Objects (classes) which model the real life biological component.
BioMight Utilities
In the screen capture below, we see some examples of BioMight’s Utility classes. These are shared between the EJBClient and EJBServer portions of the Enterprise Application. They are implemented as Serializable, as the data within them is transported across the network, and used to create the EJB on the other side.
BioMight EJBs
In the screen capture below, we see some examples of BioMight’s EJBs (Enterprise Java Beans). The **BioMightBean ** was the first EJB in the project to be created, so it contains a mix of organs and base code. In a future release, the Organs should be moved into a BioMightOrganBean. One can infer that muscles are generated in the BioMightMuscularBean, while arteries and veins are found in the BioMightVascularBean.
Create Muscle Example
Let's jump in and take a look at how BioMight assembles the Adductor Magnus muscles, and the underlying muscle tissues. As there are a pair of AdductorMagnus muscles in the human body, one in each leg, we create a collection Class and make the call to the EJB (Enterprise Java Bean) from the collection Class, AdductorMagnusMuscles .
The Create Method
The create() method calls upon the getComponents() method in the **BioMightBean **(the base EJB) to get its associated information from the database. Every Java class (in the web client) uses to get its X3D data to draw the object.
Notice the getComponents() method has a parameter Constants.AdductorMagnuMuscleRef. This is used as the primary key to retrieve the data from the database. Ensure that this constant is properly set (and spelled) in the Constants.java file, or your data will not be retur ned from the database.
We see that the Java class then uses a loop to process the data that has been returned from the database, and constructs the AdductorMagnusMuscle objects to represent the set.
An instance of AdductorMagnusMuscle will be created to represent the muscles in the right and left leg. These are represented in the database as AdductorMagnusMuscle:01 and AdductorMagnusMuscle:02 records.
Next we highlight the portion of the create() class that runs through the records that were retrieved from the database. The records are in the form of BioMightTransform objects. These objects model the Transform object defined in the X3D specification. A transform object defines a basic X3D object and when put into an X3D viewer will render a 3D image. For this example, more than one row will come back from the database. As you can see from the Java code it builds a collection of AdductorMagnusMuscle (an ArrayList). Please note the initProperty() method is called to set up an object that allows it to be seen in the JSP (web interface) and access it (it holds database keys for lookup).
Muscle Object Creation
Whereas, the AdductorMagnusMuscles class creates a bunch of AdductorMagnus Muscle objects. The AdductorMagnusMuscle class builds the actual muscle by calling upon the MuscleTissue class.
We see the _create() _method for this class below. It calls upon the MuscleTissue object's constructor, passing in the parameter for the current Muscle, AdductorMagnus.
Note: Before we get the data from the muscle tissue data from the database, the generate() method can be called to create the data for the MuscleTissue, based on the parameters the user passes in through the web interface. (For now, I turn it on until the component looks how I want it, and then I set the flag to false – it saves all those updates to the database and makes running the application much faster)
The generate() method calls upon the corresponding generateMagnusMuscle() method in the BioMightMuscularBean EJB. In the example below, we first set up the coordinates for the initial points by calling the createCylinderInPlane() method. (For now,we are mostly using octogons. As the model is perfected, we can produce better shapes.) (Give me an octogon and a starting point, and I can create a tube by pushing the points and connecting them)
The AdductorMagnus muscles attach to the pelvis and attach to the associated femur in either the left or right leg. Please note the BioMightBean points to the appropriate EJB, BioMightMuscularBeanRemote. Arteries and Veins generate methods will call upon the BioMightVascularBeanRemote.
The EJB Methods
In the BioMightMuscularBean EJB, we see the_ generateAdductorMagnus()_ method that the AdductorMagnus Java client class calls to build the actual muscle. The EJB method first performs validations and if the objects are null, it sets up default values. The startPos (start position) that is defined in the Client Java class and here in the EJB, should have the same value.
Below, we see how the component gets generated by the various Java classes.
Declare Instruction Set
In the EJB, we set up a starting point and then supply a set of instructions to create the biological component. Looking up Adductor Magnus muscles via Google web search we see that there are a pair of AdductorMagnus muscles, one for each leg. When the Client class calls getComponents(), the database will find two references for the AdductorMagnus muscles. In the database their key (comp_id) will appear as AdductorMagnus:01 and AdductorMagnus:02 and we look for those specific references here to create it. We will provide instructions for creating each one by looking at the parent ID.
As we see in the screen capture below, the getComponents() method returns a fully loaded BioMightTranform object which models the X3D counterparts properties.
The code below handles the second AdductorMagnus muscle. There are commands for move, scale, and rotate.
Get X3D
Every Java class also has a getX3D() method. In this example, the X3D is created by getting the X3D from the individual AdductorMagnus muscles. The getX3D() method will ultimately work in a few ways. Based on the constant passed in, it may get the Transform XML data directly and return it, or it will drill down deeper into the biological models to get the X3D from the objects that comprise it.
Example2
Below we see the constructors and create() method for the Liver. There is only one liver in the body, so this method gets its data from via the database directly. There is not a collection class for the Liver. As in most all cases, the method calls the_ getComponents()_ method in the BioMightBean to get the data to construct the Liver object. This brings back a list of Transform objects.
We run through the Transform objects that are returned from the database. One row will be returned by default (Liver:01), and for that object we are going to create the EpitheliumTissue. If the view level asks for more detail (as seen in the Else-Block), we will drill down to get the X3D from the subcomponent objects. Again, we the generate() method that will be called when we want to create or update an object.
Generate the Liver Below we see the generateLiver() method that calls upon the BioMightBean (EJB) to create or update the object. The liver starts at -17.75in on the Y axis for me. After setting up the octagon, the generateLiver() method in the EJB is called.
Below we see the generateLiver() method that was created in the BioMightBean EJB. The model is the same; create an octagon and provide an instruction set to create the biological representation.
Most EJB’s method call the generateFacedComponents() method creates the rows in the database based upon the set of starting points and the instruction set that is put together in the generate method.
Putting it together Below, are the steps needed to create, or overwrite a new BioMight component.
BioMight Web Code Pick the Java class that you are going to make your copy, or duplicate from. Copy and paste the Collection class and the Child class using the Ctrl-C and Ctrl-V or mouse-based copy and paste. This will give you two new files. If older versions of the files exist, delete them.
Perform a rename operation by using the Ctrl-F option which brings up the following Dialog window. Put the name of the Old Class in the Find box, and the new Java Class name in the Replace box. Use the “Replace All” feature and will do everything at once. Always make sure the “Case Sensitive Flag” is on as shown below. You will have to perform a find and replace on the lowercase name in the Collection classes only.
Each BioMight component has a generate() method. Ensure that you set the bGenerate flag to true when working on a component so that its generate() method is called. Also make sure the call to getComponents() has the proper Constant defined. As a later note, the constant, defined in Constants.java, will match up with the comp_type field/element in the SQL biocomp database table
EJB Client Code Set up the remote method call in the MuscularEJBClient, VascularEJBClient, or SkeletalEJBClient. This mechanism allows the Web Client Java classes to talk to EJB beans.
EJB Code Add the generateXXXX() method to the proper EJB class whether it be MuscularBean, VascularBean, SkeletalBean, etc. If you are working on a vein, make a copy of the +generateArtery method, as corresponding veins and arteries pretty much follow the same path.
Database Rows
Component Table - There needs to be a record for each instance of BioMight component that you are creating. Below we see an example of the Brachial Artery. Also, we see the Endothelium row that the generate() method constructed.
Group Table – This stores the relationship from a view perspective. For instance, there is only one Brachial Artery in the left arm of the human body. But, we can access the Brachial Artery from the Arm.java of from Arteries.java. The parent to child relationship is stored in the group table. If the rows are not in the group table, the component database table rows will not be picked up in the getComponents() method query in the base BioMightBean EJB.
Exporting the Libraries
Whenever you make changes to the BioMightEJB methods, such as generateFemoralArtery(), where you would update the instructions for graphic operations such as Rotate, Scale, Translate, etc. you will need to export and deploy the library so that your changes appear in the BioMight application. Start by moving your mouse over the BioMightEJB project and click the mouse to select the Export option as shown below.
Select JAR file. It should be preselected, so you may just press “Next”.
Click on the BioMightEJBClient library as that needs to be exported as well.
Grab the file using Windows Explorer and copy it to here. They reside in the Lib folder.
After making changes to the code, or updating a library, wait until the server has been updated with the latest code. Watch for the little green status bar that says “working” to complete. Below, we see that our server is not in the proper state, so a restart is needed.
Now, we see that the server is Started and Synchronized. You are ready to test your code.
BioMight Development Guide
Version 1.2