Objectreferenceanalyser (ORA)

The framework to analyse and understand applications as well as data/object references

Objectrefenceanalyser is a framework, developed in Java, that helps to understand applications, object/data correlations and their impact.
It analyzes and traverses objects and their references during the runtime of any Java application using reflection.
Then the results can be persisted as 'snapshots' or explored (optional via remote access) through diagrams and graphs in the GUI online or delayed.
Further the remote capabilities provides monitoring functionality to check the state of your application.
For exploring other data than object references, relational data can be imported from CSV-file-tables and then visualized.

Content:

Overview
Features
First Start
Usage
FAQ

Links:

Version history
Latest version as runnable applet!
Download
@Sourceforge
Latest api-doc
Forum
Quick overview (PDF)[*Antiquated*]

Overview:

    This Tool helps to:

Features:

    Object analyzing engine

    (Object-) reference visualizer

    Tool library

First start:

ORA is delivered with demo application containing some objects being analyzed at startup for demonstrational purpose. This gives an idea how the graphical interface would look like and to allow user some hands on.
To run this demo of ORA, you need to do following:
1. Extract the downloaded file and
2. Start the "executable" jar-file by either double clicking or running "java -jar <jar-file>".
3. After successful startup, you will see the result of a small number of demo objects analyzed. You can start getting familiar with the UI and the general handling before integrating it.

Screenshot

Please note: Above picture was created after setting filter to "show all" and enabling arrow drawing, anti aliases and name drawing.

In the demo application, the objects are ordered randomly by default but can be rearranged automatically by pressing the "Start graFx"-button.
In case the arranging algorithms does not suit the requirements then the user can arrange them manually as well, by just drag and drop the boxes to another position.
A hybrid scenario of using the algorithms in parallel to manual positioning, the right mouse key can be used to force a location of a box in the screen.

Usage:

The Tool has to be integrated in your application programmatically. This means there is no(!) Wizard to integrate ORA into your application or vice versa.
So it is just straight forward code based integration:(Also see Try.java which is part of every release)

        //1.   You have to instantiate a Analyser:
        AnalyserInterface ref = new ObjectReferencesCore("SomeIdentifier");
        //2.   You have to pass the to be analysed root object to the analyzer (mostly you pass some main components which hold important data):
        ref.addAndAnalyseRootObject(someObj);
        //3.   You have to start the visualizer to be able to see something
        new Visualizer(ref).start();

Once the code above was executed you will see graphical view similar than the picture in the previous section. Surly, your object structure will look different.

All the objects discovered by the analyzer starting from the given object excluding the specified packages are now represented as mouse sensitive boxes in the graphical view component.
Primitive and "boxed" primitives like String, Double ,....won't be shown as separate boxes but are visible as content of the owning objects in the information view.

On the right side there are three views available which can be changed in size and position.

Information: (Filled only once one object is selected)
                   This view consists out of four tabs:
                         Standard      Here you can see a rough summary of the object's properties.
                         Detail           This tab gives you all required details of the object.
                         Parenttree    The Parenttree allows you to traverse through the reference pointing to the object.
                         Childtree      Here you cab traverse through the tree of objects referenced to.
           Classes
                   This view provides an overview about the analysed classes and the count and allows you to highlight them by assigning different coloring.

           Objects:
                   Here is an overview provided about the objects discovered along with:
                         Names:       This are the names of the variables holding a reference to the object.
                         Children:     Number of objects referenced.
                         State:          Discovery state
                        (Also highlighted in the graphical view by different style of the box, see menu Info->Legend):                                      
                                      NEW:      Discovered initially for the first time
                                      KNOWN:    Repeatedly discovered (After reload-request)
                                      LOST:          Reference lost
(After reload-request) in case the object is not anymore discovered/referenced.

FAQ:

Please always use latest version of ora...!

How can I use the ORA through the browser?

The latest versions include a custom http-handler which will respond on an http-request by providing an applet.
Therefore please point your browser to the designated url of your remote analyser, say: http://localhost:11111 (Details please refer to "How can I use ORA for remote analyze ?")
Before please check your browser configuration by trying out the applet provided here: Latest version as runnable applet!

How can I use ORA's application monitoring capabilities?

The remote feature provides the ability to register different kind of data to be supplied to clients.
This data could be either simple POJOs, dedicated files like log files or defined monitoring objects (having implemented the monitoring interface):
    - Any object can be registered on the server to be analysed on the client
    - Different kind of files can be registered to be saved/loaded on the client-side. The files could be either log files or on demand persisted ORA-data containing exception situations to be analysed for example.
    - The monitoring objects have to designed once based on the individual needs. The interface (ora.core.base.markerClass.Monitoring) forces ORA to refresh the data during every reload request.

How can I use ORA to visualize system/module dependencies/relation or any other referencing data?

The current version of ORA supports load (and export) of any kind of relationship via CSV-file.  
CSV-Template can be generated by opening the demo application and just exporting as CSV.

    Example input from "excel" saved as CSV.
Excel view
Please note: Import of embedded lists is working only for version 2.30 and above.

    Click to download example csv-file (comma ',' separated)
    Click to download example csv-file (semicolon ';' separated)

    Imported CSV-Result in ORA:
Result in ORA
                      The separator character to be used in ORA can be chosen in the import/export file chooser dialog.

How can I use ORA for exception discovery ?

ORA provides the functionality to persist the results of the analyses without user interaction. Let us assume for e.g., you have a critical method which fails due to some non-reproducible conditions.
The old fashioned classical way would be increase the number of logs to log each object and their variables involved in your method and scrolling the log files to realize that you still missed some variables to log.
Using ORA you can increase the coverage and decrease the number of required log statements by requesting ORA to capture the objects completely including references:

    public void performCriticalAction(Object someObj) throws Exception
    {
           try
           {
                  //DoSomething(someObj);
           }
           catch (Exception e)
           {
                  // 1. You have to instantiate a Analyser:
                  AnalyserInterface ref = new ObjectReferencesCore("Exception:"+e);
                  // 2. You have to pass the to be analysed root object to the analyzer:
                  ref.addAndAnalyseRootObject(someObj);
                  // Maybe there are some more not linked objects important:
                  ref.addAndAnalyseRootObject(someOtherImportantObj);
                  // 3. You can save now the model to harddisc for later explorations
                  ref.save(new File("MyExceptionalModel"), PersistenceConfiguration.PC_BINXML);
           }
    }
          The file can now be analyzed later on to identify the wrong data.

How can I use ORA for remote analyze ?

                    ORA provides the functionality to allow remote access to the results of analyser via plain Socket connection.
                    Therefore you need to register it to get the port opened:
        DataController controller = DataController.getInstance(11111);//e.g.: port 11111 will be used as control port
        Object obj = OrderGenerator.getOrders(5, -1); //generate some objects or use your own objects
        AnalyserInterface or = new ObjectReferencesExceptSunsUIPackages("5 Orders"); //create/instantiate analyser and choose proper name
        or.addAndAnalyseRootObject(obj);//analyse objects
        controller.register(or);//register analyser for remote access
                    On the client side you need to start the Visualizer then in menu: File -> Connect to remote.

                    Please note:
                    You need to be aware that activities such as reload/edit followmode/edit exclusionlist performed on the
                    client while being connected remotely will get reflected on the remote machine immediately.

My JVM is not terminating after registering Objects for remote access?

Yes, it won't terminate by itself, as a socket was created that is listening for requests.
Either you unregister the objects the same way that you have registered them or you connect using the GUI and use right mouse button to shutdown instance(s):


How can I use ORA to get a architectural understanding ?

Most of the tools currently available use the classes as their base for application analyses and producing architectural views. They can only produce a static class model based on the code in the classes.
ORA produces so called Classview that is similar to static class model from the real state instances of the objects in memory. To see this, you need to select Classview in the UI in the top right corner or choose from  
the menu View->Classview.

How can I use ORA to find memory leaks ?

ORA tracks the difference between two reload requests by highlighting the discovery state, which can be utilized to detect memory leaks.
Therefore you apply the following steps:
  1. Reload in an initial point of your application
  2. Work with your application
  3. Return to the initial point (closing all windows/panels/frames)
  4. Request Garbage collection (from menu: Control->Request Garbage Collection)
  5. Reload
  6. Use filter new only to see newly created/instantiated objects, that not got cleared after getting back to initial point.
Now you have to check the deltas and verify whether the specific objects should be present or not.

How does ORA work ?

At the nut bolts of ORA mainly java reflection is used. Based on a given root object it traverse recursively class wise through the object structure capturing all field data and "follows" referenced objects till no more object can be found. As mentioned above, every java-object will not be treated as a object. Basic objects such as String, Double and other wrapped primitives as well as core primitives like int, long etc. will be handled as data. These will be associated with the parent object's content instead an association as a reference.
For each classlevel traversed through a handler would be identified applicable to discover the content. There are different handlers responsible for different classes, e.g. there is a Map, List and so on handler which analyse the objectclass not based on there internal fields but on the content itself which results in better outcome:

HowOraWorks

How can I see arrows indicting the direction of the reference ?

To enable you have to select Show arrows in the control area or choose from the menu View->Show arrows.  To save CPU usage, this facility is disabled by default. For better quality but more CPU consumption you can also enable Anti-alias.

Is ORA holding references to object which holds the Garbage Collector from cleaning those objects ?

No, ORA is using weak references, only. .

Can I trigger the Garbage collection manually ?

Yes, from the menu Control->Request Garbage Collection.

Why is the reload button disabled ?

This button is only enabled, if one of the root objects are referenced. In case of loading a model for example there is not reference to the original object available anymore.

Why is the edit exclusionlist disabled ?

This action is only available if a customizable analyzer was used and references to the root objects are available.

Why is the edit followmode disabled ?

This action is only available as long there are references to the root objects available.

What analyzer are out-of-the-box available ?

There are currently two types of analyzer shipped:
               

ObjectReferencesExceptSunsUIPackages

This is a predefined analyzer that excludes most common used UI-Packages from being analyzed. It extends the ObjectReferencesCore analyser.

ObjectReferencesCore

This analyzer is the core implementation and uses by default the rules from /resources/rules/CoreAnalyserRules.rls.
The definition can be done changed programmatically while instantiating or predefined in the rules file(.rls) shipped as well as through the UI (even remotely)

          

Why do I need customizable analyzer ?

In case of large and complex application the analyzed may find a reference to the jdbc-driver or other low level classes. In most cases these are not required to be analyzed.
So this packages can be excluded using the Control->Edit exclusionlist item to also reduce the number of objects to be handled.

Is there any way to configure ORA other than using these old fashioned configfile ?

Yes, any setting can be applied also through the system properties similar to the key-value pair of the configfile. The values in the system properties override logically the values in the configfile.
- The analyser can be configured through the menu Control->Configure analyser.

Can I use LOG4J for any logging purposes ?

Yes, ORA uses a generic log mechanism. It detects whether LOG4J is available and uses it by default (as per configfile).

more coming soon...





Last updated on 11.Juli 2010 by Kristian Martin