Objectwiz - User's manual Benoît Del Basso benoit.delbasso at helmet.fr Creative Commons 2 February 2010 Preface
Introduction The object paradigm is widely used for developping software applications. One of the reasons for its popularity is that it's great for mapping real-world concepts into data models. A classic architecture for a software application that use this paradigm is the Three-tier architecture (separation of the application in three layers: data, logic and presentation). The task of the data layer is to provide an abstraction for storing objects into databases, for making them persistent. In many programming languages, this type of layer has been normalized in what is usually called a persistence layer. Let's mention JPA as an example. Those framework may rely on relational databases (in that case they are called Object-relational frameworks - ORM), object-oriented databases or any other system. Their job is to make sure that the data is stored, can be retrieved, queried and modified. Objectwiz is a dynamic front-end for administrating such applications. It is possible to browse interactively the graph of objects and to manipulate data (CRUD operations, call to methods from the logic layer, etc.) directly from within the graph. Objectwiz stands between a database administration tool (such as phpMyAdmin) and a CRUD application generated from a data model. IMPORTANT NOTES: 1. Objectwiz is very generic in its design and the concepts are independent of any programming language, still it can currently only be connected to JEE enterprise applications. The reason is simple: Java offers a wide range of standards (JPA, EJBs, JNDI, JMX, etc.) that greatly simplify the task of discovering the data model, retrieving the connection to the database, etc. If you are interested in connecting Objectwiz to applications from other programming languages, please get in touch with the development team. 2. Despite all these standards, some operations performed by Objectwiz are tied to the application server and the persistence provider that is used in the target application. Therefore Objectwiz needs a few lines of code for each server and persistence provider. Currently, only JBoss and Hibernate are supported, but with little effort Objectwiz could be connected to other JEE application servers or JPA-compliant providers as well. Please open a discussion on the forums about the particular server and/or provider that you are targetting if you would like it to get supported. If you are new to object-oriented programming, Java or to the concept of persistence, enterprise beans, you might also consider to read the following articles: Java Lesson: Object-Oriented Programming Concepts Java Platform, Enterprise Edition (Wikipedia) Designing Enterprise Applications with the JEE Platform, Second Edition Java Persistence with Hibernate
Feedback Use the project page on Sourceforge to report errors or request enhancements to this documentation.
Setting up Objectwiz with a sample application: the DVD Store The DVD Store (from Seam framework) is a classic example of EJB3 three-tier application. This chapter explains how to set up Objectwiz to administrate the data of the DVD store, however these steps apply for any other JEE enterprise application. The DVD Store Browsing the object graph (current object: the film "The Nun's Story" with Audrey Hepburn)
Prerequisites In order to follow this tutorial, you will need the following items: A JBoss server instance. JBoss 4.x is recommended since there are some issues with 5.x versions and a version 6 is still a milestone version at the moment. Latest available community version is then 4.2.3.GA. The DVD Store application. It is available in the releases of Seam. Seam 2.1.2 is the recommended version to download when targetting a JBoss 4.2 server. The latest release of Objectwiz. It is available here. After downloading the files, extract them to separate directories. These directories will be refered below as jboss/, seam/ and objectwiz/.
Add shared libraries to JBoss. Copy objectwiz-core.jar to jboss/server/default/lib.
Deploy the DVD Store with embedded agent. The DVD store can be built and deployed to JBoss using the provided ant script. First, update jboss.dir to the correct path in seam/build/default.build.properties. Then, change directory to seam/example/dvdstore and run ant explode. This will build the DVD store sample application and deploy it as an EAR application in jboss/server/default/deploy/jboss-seam-dvdstore.ear. Go to this newly created directory and follow the three steps below to embed Objectwiz Agent into the application. The agent is a very lightweight Java module that exposes the application and interacts with Objectwiz front-end. Copy objectwiz-agent.jar and objectwiz.conf.xml.sample to this directory (the root of the EAR application). Rename objectwiz.conf.xml.sample to objectwiz.conf.xml and update it so that the <application> tag contains the name of the application (jboss-seam-dvdstore for the sample application). The configuration file should then look like:
<?xml version="1.0" encoding="UTF-8"?> <objectwiz> <application>jboss-seam-dvdstore</application> </objectwiz>
Add objectwiz-agent.jar as an EJB module in META-INF/application.xml, under the <application> tag.
<module> <ejb>objectwiz-agent.jar</ejb> </module>
Deploy Objectwiz front-end Copy objectwiz.ear to jboss/server/default/deploy.
Launch the server and check the applications Execute jboss/bin/run.sh to run the server. You should get a WARNING [1] along with an incomplete deployment listing [2], but that's normal behavior for the first run.
[1] java.lang.Exception: Agent corresponding to the current application was not detected: objectwiz [2] --- MBEANS THAT ARE THE ROOT CAUSE OF THE PROBLEM --- ObjectName: jboss.jca:name=objectwizDatasource,service=DataSourceBinding State: NOTYETINSTALLED Depends On Me: persistence.units:ear=objectwiz.ear,unitName=objectwiz
Wait until the two applications are deployed and check they are up and running: http://localhost:8080/seam-dvdstore. You should see a "Welcome to the DVD Store" screen. http://localhost:8080/objectwiz. You should see a "Welcome to Objectwiz!" screen. On the Objectwiz splash screen, click on "Create internal database". After a few seconds, you should be able to see a "Launch" button. If that's not the case, please refer to the troubleshooting chapter. Running Objectwiz from the first time Splash screen of the front-end (once the internal database is successfully created)
Configure access rights Access control in Objectwiz is based on the roles supplied by the application server. To be able to successfully log in to Objectwiz, a user must have the role: objectwizUser. To get write-access to the data of an application, a user must also have the role <name of the application>-RW (e.g. jboss-seam-dvdstore-RW for accessing the DVD Store sample application). The default realm for objectwiz web application is the one of the JMX console (jmx-console). Therefore, users/passwords/roles can be configured in the two following files:
jboss/server/default/conf/props/jmx-console-users.properties jboss/server/default/conf/props/jmx-console-roles.properties
NOTE: JBoss must be restarted for changes to take effect.
Launch the rich client On the web front-end (http://localhost:8080/objectwiz), click Launch and open the file that pops up (jnlp.jsp) using "Java Web Start". On the login screen, supply the credentials that you defined at Step 6. After logging in, you should see a list of two applications: objectwiz and jboss-seam-dvdstore. If that is not the case, please refer to the troubleshooting chapter. NOTE: You must have Java > 1.6 Update 12 installed on your computer. NOTE: The security certificate is currently self-signed, which means that you should expect a security warning: "The application digital signature cannot be verified". Just skip it by clicking "Run". NOTE: If this is the first time you run a JavaFX application, you may get some additionnal splash screens.
Play with the DVD Store. The DVD store is a simple front-end for an online-shop that sells DVDs and does not provide any administration back-end. You can use Objectwiz to create new films, actors and see how it's reflected in the front-end. Likewise, you can also order DVDs on the front-end and browse the associated orders in Objectwiz.
Using Objectwiz This chapter describes the various functionalities of Objectwiz using examples from the DVD Store. Please refer to the previous chapter for instructions on how to set up this sample application.
Description of the user interface The user interface of Objectwiz is composed of a toolbar and a tab panel that lets the user perform several actions at a time.
Home panel The home panel is the first tab of the interface. You cannot close it. It shows the list of persistence units that the user can manage. A persistence unit is the combination of the object data model and the actual data (i.e. the connection to the database). Click on one element of the list to access to all the available actions for the corresponding persistence unit.
Toolbar The toolbar provides shortcut for performing actions on the current persistence unit: look for objects, create new instances, perform queries, call methods from the logic layer, etc.
Persistence unit panel After selecting a persistence unit on the home panel, you are redirected to a panel that offers you basically all the actions that you can perform from the toolbar, with further explanations.
Lists of objects A screen that users will often encounter is the one that displays lists of objects (usually called list view). This view is very similar to classic relational administration tools although in Objectwiz clicking on a row will most of the time lead the user to the graph view where it is possible to interactively navigate the object graph (see below).
The object graph Objectwiz will most of the time redirect to this view when the user selects an object. This view shows the current object in the middle of the screen and the connected objects on the surrounding ellipse. This graph is customizable (see related section): on the screenshot above it is possible to see the picture because the following HTML template has been set:
<div style="height: 150px";> <b>#{title}</b> ($#{price})<br/> <img src="#{imageURL}" alt="Image" /> </div>
Without this template, the central node would look like: Moving the mouse over the central node will expand it and make action icons available. Using these icons, it is possible to manipulate the object (edit it, call a method from the business logic with this object as one of the parameters, etc.). Leave the mouse over an action icon for a few seconds to get a tooltip explaining its effect. Last but not least, this graph is interactive since clicking on one object on the ellipse will make it become the current object (= the central object). On the previous screenshot, clicking on Feature Film-drama will lead to the next screenshot. NOTE: If the data model contains unidirectional associations, Objectwiz automatically generates the opposite property for the purpose of browsing the graph. The link from films to categories in the DVD Store is an example of unidirectional association: categories do not have an attribute that references all the corresponding films but it is automatically generated (see above screenshot where the label was customized for clarity).
Scenarios
Searching for specific objects
Using filters Choose "Look for one or several existing entities" in the persistence unit panel or click on "Search entity" in the toolbar to access this search screen. Choose a class and add filters to find the desired objects. Use the arrows to navigate between pages if there are too many results. The tree with checkboxes on the right controls which columns shall be displayed. It is possible to save/load display settings for the columns (position and relative size in %) using the blue drop-down and green "plus" button on the right-hand side. Double-clicking on one row will open a new tab with the graph view of the corresponding object.
Using custom queries Choose "Perform a custom query" in the panel related to a persistence unit or click on "Perform Query" in the toolbar to access this screen. Enter a query string in one the of available languages and click "Perform query" to see the results. It is possible to use ordinal or named parameters if the query language supports it. The user will be asked to input these parameters. It is also possible to save/load queries as bookmarks that are currently shared with all the other users. The combination of bookmarks and parameters can be a nice entry point for accessing data from the model very quickly. HQL query without any parameters HQL query with one parameter
Updating objects
Creating new persistent instances Creating new objects is possible from different locations in Objectwiz. You can either: Choose "Create a new entity" in the panel related to a persistence unit; Click on "Create entity" in the toolbar to create an object from the same unit than the current tab. Click on the corresponding action button in nodes of the graph that correspond to collections of objects. You will be asked to choose which class the new object shall be an instance, or redirected directly to the corresponding form if there is no ambiguity.
Creating links between objects It is possible to link objects directly on the graph by using the corresponding action icons (see two screenshots below). Depending on the type of property, these actions will either assign the value choosen by the user or add it as another element of the collection. Using the green "plus" button, the value is created from scratch while when using the blue "down arrow" button an existing value is assigned.
Removing objects To remove an object, just click on the "red cross" action button on nodes of the graph or choose "Remove element(s)" from a list view.
Calling business logic To call a method from the logic/business layer, first choose "Call a business method" from the panel related to a persistence unit, or click "Run method" in the toolbar. The methods are these of the EJB session beans that were discovered by Objectwiz in the JNDI context of the application. Choose a method, provide the required parameters (if any) and click "Submit". The results will be shown in a list view below. When the return type is an array of bytes, the user will be proposed to download the corresponding file. NOTE: if the method returns objects from the model, you can double-click on one object of the list to open the graph view.
Customization
Customizing classes and properties It is possible to change the labels of the classes and their properties, and the order of properties. Click on "Browse unit metadata" on the panel corresponding to a persistence unit to get a tree of the classes/properties of the data model. Fields on the right can be used to change label/order of the selected object in the tree. NOTE: this look'n feel is not very friendly, it is going to be improved in upcoming version.
Creating and using query bookmarks On the panel for performing custom queries, you can either save/load bookmarks using the corresponding buttons. When saving a bookmark, the user is asked to input a short description and a name/id (NOTE: the name will be removed from upcoming versions). A list of all the bookmarks is available by selecting "Perform a bookmarked query" on the panel related to a persistence unit, or by clicking on the "Use bookmark" toolbar icon.
Troubleshooting
Recommended additional setup For easier troubleshooting, configure log service (server/default/conf/jboss-log4j.xml) to route log messages from Objectwiz (package org.objectwiz) to an independent log file (e.g. objectwiz.log).
<appender name="OBJECTWIZ" class="org.jboss.logging.appender.DailyRollingFileAppender"> <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> <param name="File" value="${jboss.server.log.dir}/objectwiz.log"/> <param name="Append" value="false"/> <!-- Rollover at midnight each day --> <param name="DatePattern" value="'.'yyyy-MM-dd"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/> </layout> </appender> (...) <category name="org.objectwiz" additivity="false"> <priority value="INFO" /> <appender-ref ref="OBJECTWIZ" /> </category>
FAQ This FAQ is to be completed. Feel free to ask for help on the mailing list or on the project page.