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!

    Comments

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

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

    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.

    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.

    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).

    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!

    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?

     

    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.

     

     

     

    Hello Kumar!

    Did you compile the classes you’ve imported? Try importing and compiling ClassExplorer.xml once again.

    Hi Nikita Savchenko, I compiled all the classes individually too. And still getting the same error. 

    Classes

    • ClassExplorer.ClassView
    • ClassExplorer.Installer
    • ClassExplorer.Router
    • ClassExplorer.StaticContent

    Did you compile them in samples namespace as shown in webapp settings? Also are you sure that nothing unexpected is set up in front of Caché which can prevent normal routing (like load balancers/other routers)?

    Kumar, try to load and instal in USER namespace or a separate, not SAMPLES.

    Hi Evgeny Shvarov,

    Tried it in a new namespace, still same problem. I guess it not able to make the REST api call. I tried running one of the method from terminal, it works from there. 

    Just tried the installation on Cache for UNIX (Apple Mac OS X for x86-64) 2017.2 (Build 744U).

    Installed in USER. works fine 

     

    There is a note in installation:

    Note that importing ClassExplorer.WebAppInstaller class will also create a /ClassExplorer application. If you want to create WEB application manually, please, do not import this class. Anyway, importing this class requires %SYS permission.

    Maybe you have not enough rights to have everything installed properly? 

    I have %All role and admin privileges  too. Tried adding it to a different HS instance on a different server and it works fine, just not working on a specific server and there is no difference in my privileges or the setup from the other one. 

    Kumar,

    Does it have the same network configuration (any load balancers/firewalls/etc)?

    So this is strange. Try installing some of my other projects like WebTerminal or Caché Visual Editor and check whether they have the same issue. If yes, double check your Caché security settings, and especially web apps and their privileges.

    You are right something is wrong in the setup on the specific HS instance, I am guessing something to do with IIS as it is routing the traffic. As I got your WebTerminal application and even that didn't work on that instance but worked on other instance. 

    I will try to create a simple REST application with just GET and try to call it and see  what is wrong. 

    On a side note what is Caché Visual Editor and where to get it from. 

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

    Hello John!

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

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

    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

    Downloaded version 1.19.2 and it is working :-)

    Issues seem to be with 1.20.0

    Hello, have tried your project and really liked it
    I have a question
    When you develop business production in Ensemble you have to keep in mind which messages are called by every Service/Process/Operation.
        And it is not enough to remember only name of message but you have to remember types of request, response and their properties.
        I think it will be very helpful if there will be ability of creating visualisation of calls' diagram
        Something like diagram which you can see at attached pic - 
        It was drawn at "Ensemble. Development" course and it really saved me from getting stuck in mix of messages' set
        As you can see there are not so many messages used.
        I can't even imagine what happens when you have to deal with big production with huge amount of different messages.
    So, here is the question: Do you know any tool/project which can give the ability of this kind of visualisation? If no - maybe it will not take so much to update Caché Class Explorer to support this kind of feature

    Hello Alexander!

    Yes, these are definitely the good points to improve the application. But most likely Class Explorer will be rewritten from scratch rather than enhanced with new features. This is because the internal framework choosed for development on the very early stages is very hard to extend.

    We’ll take a note you mentioned for the future software! Thank you! Maybe you’ll also like my other projects like Caché Visual Editor, check them out.

    This tool is very handy when trying to understand complex class hierarchies - especially because it works dynamically. One thing that would make it even more useful would be the possibility to display the list of Includes for classes. Any chance of implementing this?