Caché Class Explorer — exploring Caché in the UML notation


Hello!

This article is a small overview of a tool that helps to understand classes and their structure inside the Caché DBMS.

In short, it visualizes a class or an entire package, shows the relations between classes and provides all the possible information to developers and team leads without making them go to Caché Studio and examine the code there.

If you are learning InterSystems Caché, reviewing Caché projects a lot or just interested in something new in InterSystems Technology solutions — you are more than welcome to read the overview of Caché Class Explorer!

 

Introduction to Caché

Caché is a multi-model DBMS. You can access it by using SQL queries or interact with stored objects and procedures via interfaces available for various programming languages. But the first option is always to develop applications in the native, built-in language of the DBMS — Caché ObjectScript (COS).

Caché supports classes on the DBMS level. There are two main class types: Persistent (can be stored in the database) and Registered (are not stored in the database and play the role of programs and handlers). There are also several special class types: Serial (classes that can be integrated into Persistent classes for creating complex data types, such as addresses), DataType (for creating a user-defined data types), Index, View and Stream.

Enter Class Explorer

Caché Class Explorer is a tool that visualizes the structure of Caché classes as a diagram, shows dependencies between classes and all relevant information, including the methods code, queries, xData blocks, comments, documentation and keywords of various class elements.

Functionality

Class Explorer uses an extended version of the UML notation for visualization, since Caché has an additional set of entities that are not supported in the standard UML, but are important for Caché: queries, xData blocks, lots of keywords for methods and properties (such as System, ZenMethod, Hidden, ProcedureBlock and others), parent-child and one-many relations, class types and so forth.

Caché Class Explorer (version 1.14.3) allows you to do the following:

  • Display the hierarchy of packages, a class diagram or an entire package;
  • Edit the appearance of a diagram after it is displayed;
  • Save the current image of a class diagram;
  • Save the current appearance of a diagram and restore it in the future;
  • Search by any keywords shown on a diagram or a class tree;
  • Use tooltips to get full information about classes, their properties, methods, parameters, queries and xData blocks;
  • View the code of methods, queries or xData blocks;
  • Enable or disable the display of any diagram elements, including graphical icons.

To make the better understanding of everything that follows in this article, take a look at how classes are visualized in Class Explorer. As an example, let’s display the “Cinema” package from the “SAMPLES” namespace:

    Details and features' overview 

    The left sidebar contains a package tree. Place the cursor over the package name and click a button that appears on its right-hand side to display the entire package. Select class  in the package tree to render it along with its linked classes.

    Class Explorer can display several types of dependencies between classes:

    1. Inheritance. It is shown with a white color-filled arrow pointing in the direction to the inherited class;
    2. “Association” or relation between classes. If a field of one of the classes contains a type of another class, the diagram builder will show this as association relation;
    3. Parent-Child and One-Many relation: the rules of maintaining data integrity.

    If you point the cursor over the relation, the properties which create this relation will be highlighted:

    It must be noted that Class Explorer will not go deeper and won’t draw dependencies for classes outside the current package. It will show classes in the current package only, and if you need to limit how deep should Class Explorer look for the classes, use the “Dependency level” setting:

    The class itself is displayed as a rectangle which is split into six sections:

    1. Class name: if you point the cursor at the name of the class, you will be able to learn when it was created and modified, view the comment and all assigned keywords to the class. A double click on the class header will open its documentation;
    2. Class parameters: all assigned parameters with types, keywords and comments. Parameters in italic, as well as any properties, have tooltips and are hoverable;
    3. Class properties are similar to parameters;
    4. Methods: any method can be clicked to view its source code. The COS syntax will be highlighted;
    5. Queries: are just like methods — click on them to view the source code;
    6. xData blocks: blocks that mostly contain XML data. Clicking on them will show formatted source code in the block.

    By default, each class is displayed with a number of graphic icons. The meaning of each icon can be clarified by clicking on the Help button in the top right corner of the screen. If you need a more or less strict UML notation that is displayed by default, as well as the display of any class sections, it can be disabled in the settings section.

    If a diagram is quite large and unfamiliar to you, you can use a quick diagram search function. The class containing any part of the keyword you entered will be highlighted. To jump to the next match, just press Enter or click the search button again:

    Finally, after all the edits on the diagram are made, all unnecessary relations are removed and elements are placed on their positions to reach the desired look, you can save it by clicking a Download button in the bottom left corner: 

    When you activate a pin button , the position of elements on the diagram of the current set of classes (or a package) is going to be saved. For example, if you select classes A and B and then save the view with pin button, you will see exactly the same view when choosing classes A and B again, even after restarting the browser or machine. But if you choose only the A class, the layout will be default.

    Installation

    In order to install Caché Class Explorer, you will only have to import the latest release xml package into any namespace. Once the import is complete, you may notice that the new web app named hostname/ClassExplorer/ (the slash at the end is mandatory) appeared.

    Detailed installation instruction

    1. Download the archive with the latest Caché Class Explorer release;
    2. Extract the XML-file named Cache/CacheClassExplorer-vX.X.X.xml;
    3. Import package into any namespace using the one of the following ways:
      1. Just drag XML-file onto studio;
      2. Using System Management Portal: System Explorer -> Classes -> Import, and specify the path to the local file;
      3. Using terminal command: do ##class(%Installer.Installer).InstallFromCommandLine(“Path/Installer.cls.xml”);
    4. Read the import log — if everything is OK, you will be able to open web application at http://hostname/ClassExplorer/. If something goes wrong, please check the following:
      1. If you have enough rights to import classes into this namespace;
      2. If web application user has enough privileges to access different namespaces;
      3. If you get error 404, just check if you added a slash at the end of the URL.

    Some other screenshots

    [Screenshot 1] DSVRDemo package, hovering over a class name.

     

    [Screenshot 2] DataMining package, searching for "TreeInput" keyword on the diagram.

     

    [Screenshot 3] Method code view in JavaDemo.JavaListSample class.

     

    [Screenshot 4] Viewing the XData-block content in ClassExplorer.Router class.

     

    You can try how Class Explorer works in the standard SAMPLES namespace: demo. And here is a video review of the project.

    Any feedback, suggestions and comments are welcome — please leave them here or in the GitHub repository. Enjoy!

    Vote up!
    Vote down!

    Rating: 15

    Comments: 18 Views: 1697

    Comments

    This looks like a tremendous resource. Thanks for posting it Nikita!!

    Vote up!
    Vote down!

    Rating: 0

    Great project! Why some class elements are in Italic case(I.e. Cinema.Film class) and other not?

    Vote up!
    Vote down!

    Rating: 0

    Thanks!

    The labels in italics are hoverable. It means that user can hover over a label and get any additional information specified for the element like comment, keywords, etc. If there is nothing specified (all the keywords are default ones), then no italic font will appear.

    Vote up!
    Vote down!

    Rating: 0

    This looks very promising so far, thank you!

    Just in case you are in the market for ideas on potential new features:

    - It would be nice to have the option to only render persistent classes (i.e. to make it look a bit more like an E-R diagram).

    - in UML associations are depicted as annotations on the arrows, rather than foreign key properties of the pointing class. Again, would be nice to toggle this via an option (i.e. to be able to make it look a bit less like an E-R diagram)

    - the ability to control what to show for an individual class, e.g. I have a mega class (in terms of number of properties) that is fairly core to the system and therefore many classes point to it. I would ideally like the ability to just show the class name itself and not its members as that would unnecessarily dominate some diagrams.

    Vote up!
    Vote down!

    Rating: 0

    Feel free, Wolf, to request these features via GitHub repo issues , and, if you are brave enough, pull requests are very welcomed! This is open-source model, things might be changed easier (if you are really wanting them to be changed).

    Vote up!
    Vote down!

    Rating: 1

    Thank you Wolf for the good suggestions! Especially about UML associations.

    As Timur mentioned, you can fill the issue or feature request on GitHub's Class Explorer issue tracker, but don't expect it to be implemented fast if only it is not critical for you. Just left the suggestions there to keep things organized, if you have some time.

    Thanks for your interest on the project!

    Vote up!
    Vote down!

    Rating: 0

    Edit:

    it woks now, after we added 57772 port the url.

    thanks.

     

    Hi,

    Thanks, this is very useful.

    We followed the installation instructions, but it does not work, we get an 404 error . the URL is correct with a slash at the end.

    I noticed that if i try to create a csp page in the ClassExplorer Web application, i get an error -

    5912 = page does not exist.

     

    The application settings:

     

    What's missing?

     

    Vote up!
    Vote down!

    Rating: 1

    Hi, Nael!

    Have you seen this demo: http://37.139.4.54/ClassExplorer/?

    After installation just open the URL:  http://yourserver:57772/ClassExplorer/

    and it should work.

    Regarding you second question on CSP :

    /ClassExplorer web app is REST web app, which can be determined once the web app has Dispatch class (ClassExplorer.Router in this case).

    If so this app only serves the REST URLs which are listed in dispatch class URL map.

    Hope this helps.

     

     

     

    Vote up!
    Vote down!

    Rating: 0

    Hi,

    Yes this helps, Thanks.

     

    Regards,

    Nael.

    Vote up!
    Vote down!

    Rating: 0

    General question:  Is this available for all versions of Cache?  Or just from 2016.1 and beyond?

    Vote up!
    Vote down!

    Rating: 0

    Hello John!

    This tool is available for Caché 2013.1+ versions (REST support).

    Vote up!
    Vote down!

    Rating: 0

    I think it's available for every version with REST support in Caché. 2012.1?

    Vote up!
    Vote down!

    Rating: 0

    REST is a 2014.1 feature.

    Vote up!
    Vote down!

    Rating: 0

    You're right, Class Explorer is supported from 2014.1.

    Vote up!
    Vote down!

    Rating: 0

    Thank you to all who responded.

    Vote up!
    Vote down!

    Rating: 0

    I would REALLY like to use this very-useful ClassExplorer tool!

    But for most of my classes is simply returns "Unable to get view for ... classes".

    The code that is failing is in the JavaScript installed from the StaticContent XDATA block...

    It only works for a few of my classes and they are similar to the ones that don't work, so I don't know why.

    I am running on Cache for Windows (x86-64) 2016.2 (Build 736_0_16902U) Wed Dec 7 2016 12:55:51 EST

    Help!

    Thanks,

    Cheri

    Vote up!
    Vote down!

    Rating: 0

    Downloaded version 1.19.2 and it is working :-)

    Issues seem to be with 1.20.0

    Vote up!
    Vote down!

    Rating: 0

    Hi Cheri!

    Thanks for letting me know that something is broken. I have created an issue for your case.

    Please, check out new version 1.20.1, I have made some fixes there which should help.

    Let me know if it works!

    Vote up!
    Vote down!

    Rating: 1