DictionaryForMIDs SW Design
Architecture
DictionaryForMIDs uses a 3-layer Architecture Model:
|
hmi_java_me |
hmi_java_se |
hmi_android |
hmi_webapp |
"HMI (Human Machine Interface) layer": This layer contains the user interface, i.e. menus, display components etc. There is a separate implementation of the user interface for Java ME, Java SE, Android and HTML5. |
|
|
translation |
"Business Service Layer": Provides the translation functionality (also called "Translation Layer") |
||||
|
dataaccess |
"Data Access Layer": Provides the services to access the dictionary data. |
||||
Interface to the Translation Layer
The interface from the HMI layer to the translation layer is provided by the class TranslationExecution.
Preparation
DictionaryForMIDs uses the class Util as general purpose class for logging and other useful functions. At the start of the application a Util object needs to be created and set with Util.setUtil. For example:
UtilWin utilObj = new UtilWin(); // for Java SE windowing systems (Unix, Windows, etc.) Util.setUtil(utilObj);
Loading a dictionary
public static DictionaryDataFile loadDictionary(DfMInputStreamAccess dictionaryDataFileISAccessParam)
A dictionary is loaded with the method TranslationExecution.loadDictionary. This method returns that dictionary object that is used in subsequent translations.
The parameter dictionaryDataFileISAccessParam is the dataaccess layer definition. The Translation Layer uses dictionaryDataFileISAccessParam to access files via the dictionaryDataFileISAccessParam.
dictionaryDataFileISAccessParam is an operating system specific parameter, because operating systems offer different ways to access files. DictionaryForMIDs implements plenty of dataaccesses:
- FileDfMInputStreamAccess: normal file system access for Java SE (for Unix, Windows, etc.)
- JarInputStreamAccess: for accessing dictionary files that are packaged in Jar files
- JSR75InputStreamAccess: Java ME file access via JSR75
- ResourceDfMInputStreamAccess; Java ME file access as resources that are bundled in the application jar file
- ZipInputStreamAccess: Java ME file access to files that are packaged in ZIP/Jar files
- HTRInputStreamAccess: Javascript access to dictionary files via HTTP
- Corresponding Android file access
For more information on this see the section Implementing file access for new platforms
Executing a translation
public static void executeTranslation(TranslationParameters translationParametersObj)
TranslationParameters is a class that holds all parameters for the translation:
public TranslationParameters(DictionaryDataFile dictionary,
String toBeTranslatedWordTextInput,
boolean[] inputLanguages,
boolean[] outputLanguages,
boolean executeInBackground,
int maxHits,
int durationForCancelSearch)
|
Parameter |
Description |
|
dictionary |
Dictionary that shall be translated. This object was returned from TranslationExecution.loadDictionary |
|
toBeTranslatedWordTextInput |
word/expression that shall be translated |
|
inputLanguages |
Array with one boolean entry per language. For each language
a 'true' indicates to search for this language. For example, dictionary with 2 languages: inputLanguages[0] = true inputLanguages[1] = false -> the toBeTranslatedWordTextInput will be searched in the first language only (language1 in DictionaryForMIDs.properties). |
|
ouputLanguages |
As for inputLanguages: array with one boolean per language.
True indicates to include the translation for this language. Example with 2 languages: outputLanguages[0] = false outputLanguages[1] = true -> the translation will be taken from the second language (language2 in DictionaryForMIDs.properties). |
|
executeInBackground |
True, if the the translation shall be done in the background. If this parameter is true, then executeTranslation will then return immediately and TranslationExecutionCallback.newTranslationResult (see below) will be called as soon as the translation is complete. If this parameter is false then executeTranslation will return after TranslationExecutionCallback.newTranslationResult has been called. |
|
maxHits |
Maximum number of hits for the translation. If this maximum number is reached, then the search will end. |
|
durationForCancelSearch |
Maximum duration for the search. If the search takes more time, then the search will end. |
The result of the translation is provided via a callback interface:
public interface TranslationExecutionCallback {
void deletePreviousTranslationResult();
void newTranslationResult(TranslationResult resultOfTranslation);
}
deletePreviousTranslationResult is called by executeTranslation when the previous translation result should be deleted from the user interface. The new result is passed to the user interface with the method newTranslationResult. For a description of the class TranslationResult, see the file TranslationResult.java.
Before calling executeTranslation, the HMI needs to call Translation.setTranslationExecutionCallback with an object that provides the TranslationExecutionCallback interface:
public static void setTranslationExecutionCallback(TranslationExecutionCallback translationResultHMIObjParam)
Batch Translation
public static void executeTranslationBatch(TranslationParametersBatch translationParametersBatchObj)
The parameter translationParametersBatchObj contains several objects of type TranslationParameters (for details see the source code of class TranslationParametersBatch).
executeTranslationBatch is be used to search over several dictionaries. Each of the dictionaries, respectively translations as defined in the TranslationParameters-objects, is executed in an own thread. That means that the search is executed in parallel.
When the first translation completes, then deletePreviousTranslationResult is called. Then newTranslationResult is called upon completion of each translation thread. The calls to deletePreviousTranslationResult and newTranslationResult are synchronized, this means that only one call to these methods is active at a time.
A dictionary's properties (class DictionaryDataFile)
TranslationExecution.loadDictionary returns a dictionary object with the type DictionaryDataFile. DictionaryDataFile holds all properties from the file DictionaryForMIDs.properties.
You will need to access the data structure DictionaryDataFile.supportedLanguages. This data structure stores information about the dictionary. Here some examples on how to use the data structure:
- DictionaryDataFile.numberOfAvailableLanguages: holds the number of languages of the dictionary. Note that while many dictionaries have 2 languages, there are also dictionaries with 3 languages or even > 20 languages.
- DictionaryDataFile.supportedLanguages[languageIndex].languageDisplayText: contains the name of the language.with 'languageIndex'; languageIndex ranges from 0 to DictionaryDataFile.numberOfAvailableLanguages -1.
- DictionaryDataFile.supportedLanguages[languageIndex].isSearchable: is set to 'true' if the language with 'languageIndex' can be searched. Only those languages where isSearchable is true can have the corresponding inputLanguages set to true in the call to executeTranslation. For example, let's assume there is an unidirectional dictionary "English to German (EngGer)" which translates from English to German only (not from German to English). Let's assume that English is defined as the language1 (corresponds to languageIndex of 0) and German as language2 (corresponds to languageIndex of 1). Then supportedLanguages[0].isSearchable is true and supportedLanguages[1].isSearchable is false.
- DictionaryDataFile.supportedLanguages[languageIndex].indexNumberOfSourceEntries: contains the number of 'entries' for a language. For simple word-to-word dictionaries this is the number of words for a language where a translation exisits.
- DictionaryDataFile.infoText: contains the informational text about the dictionary (from the property infoText in the file DictionaryForMIDs.properties).
- DictionaryDataFile.dictionaryAbbreviation: contains the short abbreviation for identifying the origin of the dictionary (from the property dictionaryAbbreviation in the file DictionaryForMIDs.properties).
Using the ContentParser to parse the 'content syntax'
The texts that are returned by the translation layer via the callback TranslationExecutionCallback.newTranslationResult contain the content syntax as described in the section Content Declarations. In order to parse the content syntax and generate an output that can be conveniently displayed on the HMI, the class de.kugihan.dictionaryformids.hmi_common.content.ContentParser can be used with the method determineItemsFromContent:
public StringColourItemText determineItemsFromContent(TextOfLanguage contentText,
boolean changeInputAndOutputContent,
boolean isInput)
|
Parameter |
Description |
|
contentText |
The text that is returned within the resultOfTranslation object in the callback to TranslationExecutionCallback.newTranslationResult. |
|
changeInputAndOutputContent isInput |
Set the parameter changeInputAndOutputContent to true for dictionaries where no content definitions for the input and output language texts are provided. Otherwise set the parameter changeInputAndOutputContent to false (the parameter isInput is ignored if changeInputAndOutputContent is set to false).
The user enters an English search expression in order to get the Chinese translation. The contentText for the English part belongs to the user input; here isInput must be set to true and the ContentParser will automatically apply the predefined style "InputLanguage". The contentText for the Chinese translation is the output; here isInput must be set to false and the ContentParser will automatically apply the predefined style "OutputLanguage". As general rule, set isInput to true if contentText belongs to the language where the user did input his search expression. Set isInput to false otherwise. |
The returned object of type StringColourItemText contains a
Vector of StringColourItemTextPart
objects. Each of these StringColourItemTextPart objects contains a piece of text
along with display attributes such as colour and style of the text (for details,
please see the class StringColourItemTextPart).
In order to display the text on the HMI, the StringColourItemTextPart objects
must be read one after the other with the method
StringColourItemText.getItemTextPart,
starting with index 0. Each of the read StringColourItemTextPart objects must be
'printed' in this sequence on the HMI, according to the colour/style/etc.
information. Do not insert a space or newline between the text of two
StringColourItemTextPart objects.
Implementing file access for new platforms
At 'the bottom' of the Data Access Layer (see Architecture Layers) the access to the files is done. Files are accessed as InputStreams via the class DfMInputStreamAccess in the package de.kugihan.dictionaryformids.dataaccess.fileaccess (DfMInputStreamAccess is in the DictionaryForMIDs path of SVN). DfMInputStreamAccess is an abstract class that needs to be implemented for each Java platform. There are already implementations for several platforms (Java ME JSR-75, Java SE, Android) and file types (e.g. Jar files), see also above the List of DfMInputStreamAccess classes.
The implementation is done by inheriting from DfMInputStreamAccess and implementing the methods getInputStream and fileExists. As an example, you can look at the implementation of ResourceDfMInputStreamAccess which implements the file access for the Java ME Resources (in the Java ME path of SVN). You can see that adding file access support for a new Java platform is done with only a few lines of code.
Once there is an implementation of DfMInputStreamAccess: you need to create an object of that class and pass it to TranslationExecution.loadDictionary. The Translation Layer does then use this object to access all dictionary data files. As an example you can look at the startup code of Java ME in the class DictionaryForMIDs (just search for loadDictionary).
Diverse topics
Icons
Icons are stored in the JAR file in the following directories:
| Directory | Content |
| icons/Application | Contains the application icon DictionaryForMIDs.png. This icon is provided only with one size. |
|
icons/UIDisplayTextItems/small/12px 16px 20px 24px 32px icons/UIDisplayTextItems/big/ 20px 32px 48px |
Contains the
icons for the UIDisplayTextItems as defined in DictionaryForMIDs.languages
(respectively in the file UIDisplayTextItems.java
which is generated by the tool LanguageUIGeneration). The following UIDisplayTextItems can have an icon: - ChoiceGroup (subgroup 'small') - Alert (subgroup 'big') For these UIDisplayTextItems a PNG-file with the same ID as the UIDisplayTextItem is put in these directories. There is a subgroup 'small' and a subgroup 'big'. Within the subgroups there are directories for the different pixel sizes. For example in the directory small/16px there are the icons with a resolution of 16x16 pixels. Note that the icon for a UIDisplayTextItem must be provided in each pixel size for the subgroup. Example: in each of the 5 directories small/12px, small/16px ... small/32px there must be the file SettingsColouredItems.png. At runtime DictionaryForMIDs queries the device to determine the pixel size that fits best and then loads the icons from the corresponding directory.
Display options: Performance: We need to have the icons in the following pixel sizes: 12x12, 16x16, 20x20, 24x24, 32x32. Besides: with MIDP 3.0 also the menu commands can have an icon - so finally we will need to have icons for the menu commands also. |
Display text items for different languages /
LanguageUIGeneration tool
All display texts (such as labels, menu entries, etc.) are translated to
different languages. In the source code, for display texts , always elements of
the class UIDisplayTextItem are used. You need the LanguageUIGeneration tool when you add any display text
(UIDisplayTextItem). For a description of the use of UIDisplayTextItem and the LanguageUIGeneration tool, see
here.
Specific information for Web App
For the Web App there is additional information on the Web App development page.
Source Code
You can download the current source code either from SVN (Subversion), or, if you are not familiar with SVN, post a message in the DictionaryForMIDs forum, we will help then.
Downloading the Source Code from SVN
The sources for the DictionaryForMIDs tools and applications are maintained in
a SourceForge SVN repository. Read the
description how to access the
DictionaryForMIDs SVN repository.
Downloading the Source Code as ZIP file
An old version of of the DictionaryForMIDs source code for Java ME application is part of the
following ZIP file:
DictionaryForMIDs_3.3.0_source.zip
Note however, that the
source code of this ZIP file is older than what you will find in the SVN
repository !
The source code for the other DictionaryForMIDs tools and applications (for example
DictionaryGeneration) is directly included in the ZIP file of that
tool/application.
Building the tools and applications
Development Environments
You can use the development environment of your preference to compile, run and test the DictionaryForMIDs tools and applications. For example Eclipse, NetBeans or any other Java development environment.
For compiling the DictionaryForMIDs Java ME application, most people install Sun's Java ME SDK.
Dependencies between the tools and applications
The following dependencies exist between the tools and applications:
- DictionaryGeneration, JarCreator, BitmapFontGenerator, LanguageUIGenerator, JavaME, JavaSE and Web App depend on DictionaryForMIDs
- DictionaryGeneration, JarCreator, BitmapFontGenerator and LanguageUIGenerator depend on JavaSE
- JarCreator depends on JavaME
Building the tools and applications with build.xml
The SVN directory 'Build' contains the file build.xml. This file build.xml is used to compile and create the jar files of all tools and applications.
Here is how to use the build.xml file:
- This file build.xml should be located in directory Build
- You must have Sun's Java ME SDK installed (can be downloaded somewhere at http://java.sun.com/javame/index.jsp)
- You must set wtk.home to your WTK installation directory
- This build.xml can generate DictionaryForMIDs (Java ME and Java SE), DictionaryGeneration, JarCreator and BitmapFontGenerator
- Using: run ant in directory Build
- It runs well on both platforms windows/linux
- The jar-tool must be in the path. Otherwise there will be an error during the preverifier run.
- You also must have the antenna-bin-xxx.jar file in the Build directory (the file antenna-bin-xxx.jar is part of the Build SVN directory)
Important note: the source files are UTF-8 encoded. If you are using the old
Sun WTK (for versions <= 2.5.2), you must
set in the file ktools.properties (found somewhere under wtklib) the following
property:
javac.encoding=UTF-8
Building the tools and applications directly from development environments (Sun's Java ME SDK, Eclipse, etc.)
You can build the jar files also directly with development tools such as the
Sun Java ME SDK or Eclipse, without using the build.xml file. Also in this case,
be sure to set the UTF-8 encoding.
Test versions
Please check our forum for announcement of test versions !