HOWTO - Sashipa development
When an application is built, the XML source file is included in the generated jar file. It's handy: source code can't be lost. But it's quite dangerous because the XML file contains the connection login et password. So it's better to put critical information in an extern file, and then to reference it in the main XML file.
We can do that by using XML entity. First we create an XML file. In our example it is called demo_connection.xml. Here is its content:
<?xml version='1.0' encoding='ISO-8859-1' ?> <user>theLogin</user> <password>thePassword</password> |
Then on the top of the the main XML file, the new file is added as an entity:
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE application SYSTEM 'resources/sashipa.dtd' [
<!ENTITY br '
'>
<!ENTITY nbsp ' '>
<!ENTITY frenchDefinition SYSTEM 'resources/SashipaFrench.xml'>
<!ENTITY englishDefinition SYSTEM 'resources/SashipaEnglish.xml'>
<!ENTITY germanDefinition SYSTEM 'resources/SashipaGerman.xml'>
<!ENTITY demoConnexion SYSTEM 'demo_connection.xml'>
]>
|
Now we just have to use the entity in the element dbConnection:
<dbConnection type='odbc' dbmsType='MySQL'>
<dbConnectionString>DsnDemo</dbConnectionString>
&demoConnexion;
</dbConnection>
|
XML entities mechanism is similar to a copy/paste when the XML document is parsed (read).
NB: this operation is just a new distribution of the source code. If you change connection information, you already have to rebuild the application.
Be carefull: login and password are readable in a Java compiled file too. When the architecture is client-database we can't change that. When the architecture is client-servlet-database, then you can unzip the jar file and remove the two Servlet files (XXXServlet.class, XXXServletAnalyser.class), then rebuild the jar file (see command 'jar' in the J2SDK).
Default parameters for fields are defined into the element defaultParameterSet. For each parameter type, a common value is defined for all fields (applyOn='field') and/or for all fkFields (applyOn='fkField'). Moreover, a value specific for each field can be defined (example: applyOn='comboBoxFkField').
When the field searchs for its default value, it takes the more specific value. For example, a comboBoxFkField searchs for its default size value (type='size'). It will try to take the value for applyOn='comboBoxFkField'. If there isn't any value then the combo-box will try to take the value for applyOn='fkField'. Otherwise the value for applyOn='field' will be taken.
Colors are defined in default parameters in hexadecimal in the RGB (Red Green Blue) format. Each of these three colors has a value between 0 and ff.
The component textAreaField (applyOn='textAreaField') has a default parameter wordWrap. It must be set to 'yes' or 'no'.
Log files can be defined. They will be updated by the servlet in client-database-servlet architecture, or by the stand-alone application. They can be defined in the element server (in the part architecture of the source file).
...
</dbConnection>
<logStorage>
<mainLog><logFileStorage>
<uri>Melba_DemoContact_Main.log</uri>
</logFileStorage></mainLog>
<updateLog><logFileStorage>
<uri>Melba_DemoContact_Update.log</uri>
</logFileStorage></updateLog>
<selectLog><logFileStorage>
<uri>Melba_DemoContact_Select.log</uri>
</logFileStorage></selectLog>
</logStorage>
|
There are three logs, each is optional:
The log Main records informations about all session opening and closing (ie each time an client application starts or closes there are a new line in this log). NB: in a client-servlet-database architecture, information stored in this file are stored in the servlet container log too.
The log Update records SQL INSERT, UPDATE and DELETE queries when they are executed.
The log Select records SQL SELECT queries. This log is usefull for debugging generated queries. But do not keep it in production !
You can make an application that transforms (and displays !) all data to lower case or upper case. Just modify a default parameter:
<defaultParameter applyOn='textFormat' type='valueModifier'>upperCase</defaultParameter> |
You can choose lowerCase, upperCase or nothing.
Moreover, it's possible to make criteria case-insensitive (for researchs...):
<defaultParameter applyOn='textSchemaColumn' type='criteriaCaseSensitive'>no</defaultParameter> |
If you want to developp a read-only application, then you have to remove adding buttons in menus, insert, update, delete queries in cardForm (cardSchemaTableRef ... queries='s'), adding buttons in listForms (element insertScreen) and in fkFields, etc..
No problem...
On the other hand if you already have a complete application, then perhap's you'll be enjoy to build a read-only version, without modifying all the XML source code.
To do this, just add a new element 'guiInstance' in the architecture:
<architecture>
... your previous guiInstance ...
<guiInstance name='guiConsultation' type='application' readOnly='yes'>
... the same content that the other guiInstance ...
|
The generated software will not contain any code for updating, inserting, deleting.
NB: An attribute 'readOnly' is available for the element 'server' too. And this attribute will remove from the server, all the code for updating, inserting, deleting. So the server will accept only queries for reading.
We examine here a code auto-generated by Database2Sashipa.
<screen name='SMMain'>
<title>Demo database</title>
<formSet>
<menuForm>
<menuTitle height='70'>Demo database</menuTitle>
<firstButtonLocation x='100' y='150' />
<buttonSize w='400' h='36' verticalGap='18' />
<menuButtonList>
...
</menuButtonList>
<menuComeBackButton />
</menuForm>
</formSet>
<screenComeBackButton enable='no' />
</screen>
|
Each screen has a comeBack button, except when we specify to not doing that: screenComeBackButton enable='no'.
The button label is 'Quit' for the first application screen and 'Come back' for the others. These two labels are defined - like all other labels - in the language file (<melbalab-home>/src_xml/resources/SashipaXXX.xml).
A menuForm can display a 'comeBack' button at the last position. For doing that, just add the empty element menuComeBackButton. The label for this button is defined like the label of the screen comeBack button.
You can easily add a new language to the Sashipa-Melba technology. You don't need to develop anything.
1) Translate a language file.
All messages and labels are defined in a language file. So, do a copy of one of the files <melbalab>/src_xml/resources/SashipaXxx.xml and then edit it. Take care to the encoding. Translate all markup contents to the new language. But do not change any markup or attribute names, or any attribute values ! Just translate markup contents.
Then there is one attribute value to change. You have to give a name to the first element:
<languageDefinition name='yourNewLanguage'> |
2) In your Sashipa application: adding the language as a new entity.
In your Sashipa application, at the top of the file, you can add your new language file:
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE application SYSTEM 'resources/sashipa.dtd' [
<!ENTITY br '
'>
<!ENTITY nbsp ' '>
<!ENTITY frenchDefinition SYSTEM 'resources/SashipaFrench.xml'>
<!ENTITY englishDefinition SYSTEM 'resources/SashipaEnglish.xml'>
<!ENTITY germanDefinition SYSTEM 'resources/SashipaGerman.xml'>
<!ENTITY yourNewLanguageDefinition SYSTEM 'resources/SashipaYourNewLanguage.xml'>
]>
|
3) In your Sashipa application: using the new language file.
In your Sashipa application, in the architecture part, you just have to use your language file:
<architecture>
...
<languageDefinitionSet mainLanguageDefinition='yourNewLanguage'>
&yourNewLanguageDefinition;
</languageDefinitionSet>
</architecture>
|
NB: For adding a language to the Database2Sashipa program, you have to modify a Java source file (databasesashipa/Database2Sashipa.java) and then rebuild the program. Sorry...
Important: once you have translated the language file in a new language, please share your work for other users.
Several DBMS provide a data type for boolean values. When you specify a boolean column in a Sashipa source file, the formatter of DBMS data type for boolean is assumed if existing. If boolean values are stored in integer columns of the DBMS, you can specify like this:
<database name='dbDemoContact'>
<physicalName>DemoContact</physicalName>
<singularName>Demo Contact</singularName>
<dbConfig booleanStoredAsInteger='yes' />
...
|
It can be usefull for databases that are migrated from Oracle to PostGreSQL for example.
© Copyright 2003 Sashipa-Melba Team. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License as much as this note clearly appears.