Ok, your project is in need of one or more database editors, and we are going to add them to it right now!

Adding a MaxBase Bean into the Visual Composition Editor (the white space where you assemble beans and code) is quite easy: just select the Bean category where you stored the MaxBase bean, and the following new icon will appear there:

Select it and then click where you want it to be placed, like in the picture (where the newly created MaxBase instance has been named 'Arti'):

By the way, the window "Mimages: prototipo" that you see in the above picture is not distributed with MaxBase, because it was taken from a project of mine. Its only purpose is to let us see how to make MaxBase and the rest of your project coexhist and interact.

At this point 'Arti' would still not show, if we ran the program, because Visual Age for Java doesn't know how and when to instantiate MaxBase. What we want to do is to intercept an event, the pressing of the button 'Lancia', in order to attach to it an action, the instantiation and customization of the Arti bean. Under Visual Age for Java, this task is accomplished by right-clicking on the button, and choosing 'Connect -- actionPerformed'; a dashed line will appear: move the mouse over Arti and click on it, then you will be prompted with a number of possible methods to call via a pop up menu.

None of the properties and methods of interest to us (for this example) are in that menu, so we must select "All Features..." like in the following picture.

Shortly thereafter a window will appear, prompting us to select a method, event or property to be called when the pressing of the button 'Lancia' happens.

The first method to call would be the default constructor, MaxBase(), but since VisualAge for Java automatically instantiates the beans when they are first used, we can safely skip that step. We choose the activeDB property instead. At this point Visual Age for Java will create a path between the button 'Lancia' and 'Arti', but the line will remain dashed meaning that a parameter is still missing. We can directly supply the required parameter (that tells MaxBase which database to open) or connect the dashed line to the value of the text field to let the user change the location where to look for a database (as I did later in my project).

If we ran the example at this point, we would have the 'Mimages: prototipo' window spawning the MaxBase instance (Arti) after the 'Lancia' button has been pressed. Mission accomplished!

But wait, is this all we can do with the MaxBase bean? Of course not! MaxBase can interact with other objects and beans in several ways. Here is how.

What you can do with the MaxBase Bean

• First off, you can invoke some public MaxBase methods, read and write MaxBase properties in order to accomplish tasks. They (methods and properties) are listed in the bean features under VisualAge for Java Visual Composition Editor. Using this mechanism you can also pass text resources (say you want to translate MaxBase into a different language than english) to the bean.

• Another option is to replace MaxBase add & modify panel so you can give your application a more professional look (not to mention the possibility to have a more strict control on the entered data, and their source). A mechanism is provided to let your add & modify panels communicate with different MaxBase beans (say you want to retrieve a list of suppliers to present to the user when setting up the on sale items' add panel)

• Finally, you can add your own features to MaxBase, not only in the main panel as with plugins but everywhere, and this works also with applets (no need for external INI files that would break the virtual sandbox).

Several methods to control MaxBase are available:

String[][] dbinfo()

with this method you can retrieve information about fields of a MaxBase instance. The returned values are in the following form:

String deleRec(String[] sToDele, boolean bDelete)

Delerec is used to delete/undelete one or more records.

sToDele[0] has to be the total number of records to be (un)deleted, and sToDele[n] is the ACTUAL position of the n-th record to be (un)deleted on the database (NOT A NUMBER RELATIVE TO AN INDEX).
The first record on the database is 1 (one).

When bDelete = true, the records are to be deleted,
when bDelete = false, the records are to be undeleted.

No errors will come by deleting an already deleted record, or the other way around. Modirec returns one of the standard JRXDbase error codes.

void deselectAll()

This method deselects all the records on screen (if there are any selected, of course).

void disconnect()

This method disconnects from the currently in use database (if any).

void externAddStore(String[][] sAddArr)

This method is used to externally add records to a database represented by a MaxBase instance. The parameter matches the sRecordVal parameter of the addRecord method of the AMInterface class (described below).

void externModiStore(String[][] sModiArr)

This method is used to modify records in a database (represented by a MaxBase instance). The parameter matches the sRecordVal parameter of the modiRecord method of the AMInterface class (described below).

String[][] loadRecWithFilter(String sIdx, String sHowManyRec, String sStart, boolean bForward, String sFilt)

This method lets you do a query on a MaxBase instance (like a SELECT statement with SQL). The parameters mean:

sIdx is the index on which you want the returned records to be ordered.

sHowManyRec is the maximum number of the records that you want returned. This value can be numeric (a String representing a number, like '190', or the keyword "ALL" if you want all of them).

sStart is the record from which to start loading records. Valid values can be numeric or you can use the "LAST" keyword -- which means "start from the last record in the archive".

bForward can be true or false, and indicates that you want to retrieve the record going forward or backward.

sFilt is the filter to be used.

String[][] peekSelected()

This method returns information about the selected records in a MaxBase instance. The returned values are:

void refreshView()

Use this method to force the refresh of the current view (showed records in a MaxBase instance).

void selectAll()

This method Selects all the records currently loaded (if there are any, of course).

Several useful properties are readable/writeable. Most of them (externalAddModi, PluginFactory, LPParent) are there to let MaxBase know which are the other classes that will interact with it, and so they are to be used primarily in write mode.

activeDB is a property (String); it is used to make MaxBase connect to a database. The string can be a plain file name (ending with the .dat extension) or an URL in the form: mbase://host.domain:port(password) or mbase://host.domain:port . Of course the latter is used when no password is needed on the server. Note: If you change the value of this property and MaxBase is already accessing a database, the currently being accessed db will be closed, and the new one opened.

MBFilter is another (String) property; it is used to force a filter in a MaxBase instance. Set MBFilter with the very same strings you would use to set filters from inside MaxBase.

externalAddModi is a property that lets you tell MaxBase which external add & modify panels to use. An add & modify panel is basically an object (often of type java.awt.Frame) that implements the nrio.AMInterface interface. If the externalAddModi property of a MaxBase instance is not set to NULL, whenever an user chooses to add or modify a record MaxBase will call the addRecord/modiRecord methods of the object represented by externalAddModi. If, on the contrary, externalAddModi is set to NULL, MaxBase will use its own GUI to let the user add/modify records.

The methods required by AMInterface are:

void addRecord(String[][] sRecordStr, String[][] sRecordVal, LPInterface LPfather, MaxBase MBInstance)

The above method gets called when the user chooses "add record" from the MaxBase user interface. The parameters passed are:

Note: At this time, MaxBase only lets you add or modify one record at a time, so the only meaningful value for j in this method is 1. Of course, your add & modify panel could prompt the user for new records until the user hits some kind of 'cancel' button and send them one by one to MaxBase as they are entered.

Note2: You may ask 'why should I get empty values from MaxBase? Can't I just build my own string array to store my data?'. Well, I did that so you can get the values from MaxBase, fill them with the data that the user will provide and then send the sRecordVal object back to MaxBase (with the ExternAddStore MaxBase method). Less work on your side.

MBInstance is the MaxBase instance that called our add & modify panel. Needed, because you need to know where to send the data entered by the user.

LPFather is an instance of an object of type LPInterface (see below)

void modiRecord(String[][] sRecordStr, String[][] sRecordVal, LPInterface LPfather, MaxBase MBInstance)

This method is similar to addRecord, but in sRecordVal you will find the actual data to modify (note: you will be passed one record at a time).

LPParent is a property that defines an object of type nrio.LPInterface, which is an interface that must implement the following method:

String[][] processRequest(String sCommand, String sDBSource, String sDBTarget)

This interface is here only to set a standard way of passing requests among instances of MaxBase. Note that, unlike externalAddModi, this is here only for your convenience -- MaxBase itself will not use this property. What use does it have? If the object that creates a MaxBase instance (could be an applet, a program, or simply another class) implements this interface, you will be able to use it as a "dispatching center" for multi-db operations.

Let's suppose you want to use some fields of a database in another one, e.g. supplier names in an item database. You would, most probably, let the user choose from a list of suppliers instead of having him/her enter a name by hand, so you can ask (from inside the add/modify panel of the items database) the object represented by LPParent to send requests to the suppliers database ("send all suppliers' names"). Normally there will be an object implementing LPInterface and launching several instances of MaxBase (like the "mimages: prototipo" window in the above example -- but it needs not to be visible, of course) and serving the cross-database requests of these MaxBase instances.

Using this technique is not compulsory, of course, and you can choose to implement your own way to make more DBs communicate.

PluginFactory is a property which represents an object of type nrio.MBPlugin (nrio.MBPlugin is an interface); it is used to add features to MaxBase. Let's see how.

You must implement somewhere (in the applet, program or whatever else is controlling the MaxBase instance(s)) nrio.MBPlugin, and this means implementing the following methods:

void pluginLaunch(String sTextLabel)
String[] sendMenu(String sMenu)

After you instantiate MaxBase, you set the PluginFactory property of MaxBase making it point to the controlling program/applet/class, like this:

myMBInstance.setPluginFactory(MBPlugin this);

from there on, before MaxBase displays a panel to the user it asks your program to provide (if there are any) the strings containing the text labels for the buttons to be added. It does this by calling your program's sendMenu method, passing the name of the panel that's going to be displayed as a parameter. Here is a listing of the names used to identify the panels:

addfield
addrecord
changelength
changename
changenameselect
changeidx
changeidxselect
confirmdeldb
confirmdelrec
createdb
data
dbrelated
dbtools
dbutils
delfield
fieldrelated
filter
formview
main
modirecord
properties

Example: the user selects the "data.." button in the main MaxBase panel, so MaxBase calls your program's sendMenu method using as a parameter the string "data". If your program wants to add one or more buttons to that panel, it must return the string array containing the names, else the null value.

If the user presses one of your buttons, your program gets notified via the pluginLaunch method, passing as a parameter the text (label) of the button pressed.

So, say that the user presses the "e-mail them" button (that you provided via sendMenu as described above), MaxBase calls your program's pluginLaunch method with parameter "e-mail them", and your program can do whatever it wants (it could, for example, call MaxBase's peekSelected() method to ask for the selected records, and then send an e-mail to the people represented by the records).

Since this technique doesn't rely on external .ini files as the user-defined plugins, it works everywhere, even in a browser (browser Java problems allowing, of course :-)).

resources is a property that lets you specify the text properties for the MaxBase instance. The usual comments apply (using "-" as a button label disables that button, etc).

NOTE: You must provide all of the resources in an indexed array; you can build the resources using a method like the following in your programs.

Click here to get the (Java) listing of the prepareResources method.