xulu/trunk/readme.txt

==============================================================
=== XULU README (2010-02-10, Martin Schmitz)               ===
===                                                        ===
=== http://wald.intevation.org/projects/xulu/              ===
=== http://wald.intevation.org/projects/schmitzm/          ===
==============================================================
This file contains some informations ...

(1) about the XULU modelling platform
(2) how to proceed after the first SVN checkout
(3) about the folder structur of XULU
(4) how to start XULU
    a) Requirements
    b) Start XULU from command line
    c) Start XULU from Eclipse
(5) how to develop XULU


-----------------------------------------------------------
(1) General informations about XULU
-----------------------------------------------------------
XULU (eXtendable Unified Land Use Modelling Platform) is a stand-alone
Java software which was designed as a part of my diploma thesis (Martin Schmitz,
2005, Institite of computer science, University of Bonn/Germany).
The goal was the create a generic framework, which provides general functionalities
needed for (simulation) modelling, without any relationship to a concrete
model context:
- data maintenance
- data types
- data import/export
- data visualisation
- GUI

With these components implemented once (--> XULU) there is no further need to
take into account during implementation of any model. The model designer and
programmer can concentrate on implementing the model algorithm.
The interfaces to the upper mentioned components are realised as plugins,
so the field of application is not static.
Because the close cooperation with the ZFL (Zentrum für Fernerkundung der
Landoberfläche) and IMPETUS (http://www.impetus.de) the most plugins which
are currently implemented are for land use modelling:
- maintain raster and vector data (based on the Geotools Java library)
- layer based geo visualisation (based on the Geotools Java library)
- raster based models

But generally - with implementing appropriate plugins - XULU can also be used for
complete other application fields


-----------------------------------------------------------
(2) Initialize XULU after the first SVN checkout
-----------------------------------------------------------
The XULU folders contain multiple files to configure defaults for
the XULU main application as well as for XULU plugins.
Because the "normal" user defined changes on these files should not be
updated in SVN, these configuration files are initially located in the
"defaults" folder, instead of their "correct" location.

Therefore after the first SVN checkout you have to call the

          initXulu.bat  (on Windows systems)
     or   initXulu.sh   (on Linux systems: first call "chmod +x initXulu.sh"
                                           to make the file executable!!)

once to copy the configuration files from the "defaults" folder to their
expected locations. Afterwardst you can make changes on all config files
without any unintended effect on the whole XULU community.

The default behavior of "InitXulu.bat" is not to overwrite files if they
already exist. In case of trouble (e.g. deleted or damaged config files)
you can call
                    InitXulu.bat /reset
                or  InitXulu.bat /init   (no overwrite confirmation!)

to overwrite all configuration files with their defaults.

NOTE: PLEASE DO NOT CHANGE (AND/OR COMMIT) FILES IN THE
      "DEFAULT" FOLDER!!


-----------------------------------------------------------
(3) The folder structure of XULU
-----------------------------------------------------------
main folder: The main folder contains some configuration files for
             the XULU main application as well as the startXulu.bat
             which can be used to start XULU from out of an
             development environment (like Eclipse):
             - InitXulu.bat: initializes the folder structure after
                             the first SVN checkout (see (2))
             - DefaultProperties: Defaults for XULU properties; after
                                  the first XULU start a new file
                                  "XuluProperties" is created with the
                                  user defined properties
             - registry.xif: contains the plugins used in XULU
             - readme.txt: this file :-)

defaults: Contains default configuration files for the XULU main
          application and plugins. By calling "InitXulu.bat" (see (2))
          these files are copied to the expected locations.
          NOTE: PLEASE DO NOT CHANGE (AND/OR COMMIT) FILES IN
                THIS FOLDER!!

classes: Contains the compliled java classes of the XULU application
         and plugins.

doc:     Contains the JavaDoc for Xulu. Also the target folder of
         "makeDoc.bat"

lib:     Contains all the external libraries required to run/compile XULU.
         All JARs in this folder must be integrated in the Java classpath.

dist:    Contains the current version of the XULU classes as JAR
         so Xulu can be started without compile the source code
         for your own

plugin:  Contains configuration files for XULU plugins.

src:     Contains the java source code of the XULU application and plugins.

Temp:    Usually empty. Needed for temporary files.


-----------------------------------------------------------
(4) How to start XULU
-----------------------------------------------------------

a) Requirements
---------------
Besides the external libraries in "lib" folder, it is required that
the following components are installed on system:
- JRE 1.6
- JAI 1.1.3

b) Start XULU from command line
-------------------------------
To start XULU from command line there are 2 main variants:

 1) "startXulu.bat /useXuluJar"     (Default)
    uses the XuluModellingPlatform.jar and SCHMITZM.jar from the
    "lib" folder to run XULU. This option is recommended, if you
    only want to "use" XULU and not to develop.

 2) "startXulu.bat /useXuluClasses"
    uses the "classes" folder to run XULU. Use this option, if you
    want to take your own changes (or plugin extension) take effekt.
    This option requires that
      - XULU is previously compiled to "classes" folder

c) Start XULU from Eclipse
--------------------------
t.b.c.
Important: SCHMITZM must be integrated in Classpath with
           higher priority than Geotools


-----------------------------------------------------------
(4) How to develop XULU
-----------------------------------------------------------
t.b.c.


===========================================================
http://wald.intevation.org/projects/xulu/
http://wald.intevation.org/projects/schmitzm/
===========================================================
1	mojays	2	==============================================================
2	mojays	79	=== XULU README (2010-02-10, Martin Schmitz) ===
3	mojays	2	=== ===
4			=== http://wald.intevation.org/projects/xulu/ ===
5			=== http://wald.intevation.org/projects/schmitzm/ ===
6			==============================================================
7			This file contains some informations ...
8
9			(1) about the XULU modelling platform
10			(2) how to proceed after the first SVN checkout
11			(3) about the folder structur of XULU
12			(4) how to start XULU
13			a) Requirements
14			b) Start XULU from command line
15			c) Start XULU from Eclipse
16			(5) how to develop XULU
17
18
19
20			-----------------------------------------------------------
21			(1) General informations about XULU
22			-----------------------------------------------------------
23			XULU (eXtendable Unified Land Use Modelling Platform) is a stand-alone
24			Java software which was designed as a part of my diploma thesis (Martin Schmitz,
25			2005, Institite of computer science, University of Bonn/Germany).
26			The goal was the create a generic framework, which provides general functionalities
27			needed for (simulation) modelling, without any relationship to a concrete
28			model context:
29			- data maintenance
30			- data types
31			- data import/export
32			- data visualisation
33			- GUI
34
35			With these components implemented once (--> XULU) there is no further need to
36			take into account during implementation of any model. The model designer and
37	mojays	132	programmer can concentrate on implementing the model algorithm.
38	mojays	2	The interfaces to the upper mentioned components are realised as plugins,
39			so the field of application is not static.
40	mojays	132	Because the close cooperation with the ZFL (Zentrum für Fernerkundung der
41	mojays	2	Landoberfläche) and IMPETUS (http://www.impetus.de) the most plugins which
42			are currently implemented are for land use modelling:
43			- maintain raster and vector data (based on the Geotools Java library)
44			- layer based geo visualisation (based on the Geotools Java library)
45			- raster based models
46
47			But generally - with implementing appropriate plugins - XULU can also be used for
48			complete other application fields
49
50
51			-----------------------------------------------------------
52			(2) Initialize XULU after the first SVN checkout
53			-----------------------------------------------------------
54			The XULU folders contain multiple files to configure defaults for
55			the XULU main application as well as for XULU plugins.
56			Because the "normal" user defined changes on these files should not be
57			updated in SVN, these configuration files are initially located in the
58	mojays	132	"defaults" folder, instead of their "correct" location.
59	mojays	2
60			Therefore after the first SVN checkout you have to call the
61
62	mojays	13	initXulu.bat (on Windows systems)
63			or initXulu.sh (on Linux systems: first call "chmod +x initXulu.sh"
64			to make the file executable!!)
65	mojays	2
66			once to copy the configuration files from the "defaults" folder to their
67	mojays	132	expected locations. Afterwardst you can make changes on all config files
68	mojays	2	without any unintended effect on the whole XULU community.
69
70			The default behavior of "InitXulu.bat" is not to overwrite files if they
71			already exist. In case of trouble (e.g. deleted or damaged config files)
72			you can call
73	mojays	13	InitXulu.bat /reset
74			or InitXulu.bat /init (no overwrite confirmation!)
75	mojays	2
76			to overwrite all configuration files with their defaults.
77
78	mojays	13	NOTE: PLEASE DO NOT CHANGE (AND/OR COMMIT) FILES IN THE
79	mojays	2	"DEFAULT" FOLDER!!
80
81
82			-----------------------------------------------------------
83			(3) The folder structure of XULU
84			-----------------------------------------------------------
85			main folder: The main folder contains some configuration files for
86			the XULU main application as well as the startXulu.bat
87			which can be used to start XULU from out of an
88			development environment (like Eclipse):
89			- InitXulu.bat: initializes the folder structure after
90			the first SVN checkout (see (2))
91			- DefaultProperties: Defaults for XULU properties; after
92			the first XULU start a new file
93			"XuluProperties" is created with the
94			user defined properties
95			- registry.xif: contains the plugins used in XULU
96			- readme.txt: this file :-)
97
98			defaults: Contains default configuration files for the XULU main
99			application and plugins. By calling "InitXulu.bat" (see (2))
100			these files are copied to the expected locations.
101	mojays	13	NOTE: PLEASE DO NOT CHANGE (AND/OR COMMIT) FILES IN
102	mojays	2	THIS FOLDER!!
103
104			classes: Contains the compliled java classes of the XULU application
105			and plugins.
106
107			doc: Contains the JavaDoc for Xulu. Also the target folder of
108			"makeDoc.bat"
109
110			lib: Contains all the external libraries required to run/compile XULU.
111			All JARs in this folder must be integrated in the Java classpath.
112
113	mojays	14	dist: Contains the current version of the XULU classes as JAR
114			so Xulu can be started without compile the source code
115			for your own
116
117	mojays	2	plugin: Contains configuration files for XULU plugins.
118
119			src: Contains the java source code of the XULU application and plugins.
120
121			Temp: Usually empty. Needed for temporary files.
122
123
124			-----------------------------------------------------------
125			(4) How to start XULU
126			-----------------------------------------------------------
127
128			a) Requirements
129			---------------
130			Besides the external libraries in "lib" folder, it is required that
131			the following components are installed on system:
132			- JRE 1.6
133			- JAI 1.1.3
134
135			b) Start XULU from command line
136			-------------------------------
137			To start XULU from command line there are 2 main variants:
138
139			1) "startXulu.bat /useXuluJar" (Default)
140			uses the XuluModellingPlatform.jar and SCHMITZM.jar from the
141			"lib" folder to run XULU. This option is recommended, if you
142			only want to "use" XULU and not to develop.
143
144			2) "startXulu.bat /useXuluClasses"
145			uses the "classes" folder to run XULU. Use this option, if you
146			want to take your own changes (or plugin extension) take effekt.
147			This option requires that
148			- XULU is previously compiled to "classes" folder
149
150			c) Start XULU from Eclipse
151			--------------------------
152			t.b.c.
153	mojays	14	Important: SCHMITZM must be integrated in Classpath with
154			higher priority than Geotools
155	mojays	2
156
157			-----------------------------------------------------------
158			(4) How to develop XULU
159			-----------------------------------------------------------
160			t.b.c.
161
162
163			===========================================================
164			http://wald.intevation.org/projects/xulu/
165			http://wald.intevation.org/projects/schmitzm/
166			===========================================================