Upgrading from 1.1.* to 1.2

If you used LSC 1.1.x, you will notice that many things are done differently in versions 1.2.x. The core of the software has not changed much, but the interactions with it have.

Here is a description of major changes and their impact. Details on upgrading your configuration are below.

Previous versions would generate objects and beans depending on the objectClass of the LDAP entries you were synchronizing. This process was usually done by the graphical wizard (AntInstaller), or through the ant lsc::_generator command.

This generation was required because basic synchronization files contained methods names after the attributes to synchronize (for example, getGivenName(), getSn(), etc). As of LSC 1.2.0, attribute names are just parameters, not method names. Objects no longer exist, and the new SimpleBean can be used in place of most specific beans.

In previous versions, a lsc-core library contained generic code, and a lsc-sample project was provided for users to adapt and insert their own configuration and classes. LSC could be run either from within this project, via the command ant lsc::synchronize or by making a separate directory with the src/install/make-lsc-archive.sh script.

Since code generation is no longer required, there is no need for lsc-sample anymore. The new download is an archive containing standard UNIX directories (bin, etc, lib, etc), much like the one previously generated by the old make-lsc-archive.sh script. All configuration is done via configuration files under the etc directory.

Ant and Maven, two developer tools for Java projects, were required to use LSC 1.1. This was because the generated code needed to be compiled before running.

As of LSC 1.2.0, Ant and Maven are no longer necessary and their configuration files (pom.xml and build.xml) are not included in the main download. All the old actions such as ant lsc::synchronize have been replaced by simple commands in bin/. To synchronize, run bin/lsc.

Note: If you choose to download the source code, Maven is still required.

The configuration file database.properties is obsolete. Database connection properties are now read from the main lsc.properties file. This file is also used to specify request names to use from sql-map-config files.

log4j and common-logging were replaced by sfl4j (for the API), and LogBack (for the implementation). The most visible result is that logging configuration is no longer done in the log4j.properties file but in the logback.xml file.

For most installations, the following steps will be sufficient. However, if you did one of the following, you'll need to look at the complex scenario below:

• You modified the Java code of one of the generated objects or beans.
• You wrote specific Java classes extending LSC's core classes, such as AbstractSynchronize, AbstractLauncher or SimpleSynchronize.

If you didn't do any of the above, this simple scenario will be sufficient. Read on, and follow these steps:

1. Download the latest 1.2.x dist archive and uncompress it. The result is the main LSC directory for 1.2.
2. Copy your old lsc.properties file into the etc directory under the main LSC directory. This file will be in your old project, under etc/lsc.properties or src/test/resources/lsc.properties.
3. Edit the new lsc.properties file:
   1. Delete taskType properties lines (like lsc.tasks.MyTask.taskType = db2ldap)
   2. Delete object properties lines (like lsc.tasks.MyTask.object = org.lsc.objects.pPerson)
   3. Replace all bean properties values (like lsc.tasks.MyTask.bean = org.lsc.beans.inetOrgPersonBean) with the value org.lsc.beans.SimpleBean.
4. Open your old log4j.properties file, and copy it's whole content into the log4j to logback translator. Copy and paste the result into the file logback.xml in the new LSC directory, under etc.
5. Edit this last file, etc/logback.xml:
   1. Replace all occurrences of org.lsc.utils.LocalizedJndiModificationsLayout with org.lsc.utils.output.LdifLayout
   2. Replace all occurrences of org.lsc.utils.log4j.csv.CsvLayout with org.lsc.utils.output.CsvLayout
   3. Replace all occurrences of ConversionPattern> with pattern>
   4. If you have a pattern with the convertion word l (the letter L) replace it with L
   5. If you have a rollingPolicy you have to specify a configuration ofr it (see : http://logback.qos.ch/codes.html#tbr_fnp_not_set

Unless you have a db2ldap synchronization, this should be all. If you do, read on.

For db2ldap synchronizations only:

1. Copy all lines from your old database.properties file (usually in etc/database.properties or src/test/resources/database.properties) and prefix them with “src.database.” and then add them to your new lsc.properties file.
2. Copy any XML files defining sqlMaps from your old project (usually under etc/sql-map-config.d/ or src/impl/java/org/lsc/persistance/xml) into the new directory, under etc/sql-map-config.d/.
3. Edit your new etc/lsc.properties:
   1. Replace the task.srcService property (like lsc.tasks.MyTask.srcService) with org.lsc.service.SimpleJdbcSrcService.
   2. Add two properties to each db2ldap task, lsc.tasks.MyTask.srcService.requestNameForList and lsc.tasks.MyTask.srcService.requestNameForObject. Set their values to the IDs of the select statements in the sqlMap file you just copied to etc/sql-map-config.d/.
4. Edit the sample sql-map-config.xml in the new directory, under etc/sql-map-config.xml and add a line for each of the XML files in etc/sql-map-config.d/ like this:

<sqlMap url="file://${lsc.config}/sql-map-config.d/Activity.xml"/>

(Activity is an example name, yours will be different)

Now, you should be ready to go! To run LSC, use the bin/lsc command, with the same options as previously (for example: bin/lsc -s all).

Depending on what you modified in your LSC 1.1, the upgrade path will be different.

• If you modified a generated object:

Objects (POJO) no longer exist in LSC 1.2. Whatever you changed in this Java file must be done in a different was to be compatible. In almost all cases, anything achieved in objects can be replaced with syncoptions.

• If you modified a generated bean:

It is preferable to move any specific code from your bean to syncoptions.

If this is not possible, or you don't want to, you can continue using your specific bean with LSC 1.2. In this case, it is simplest to continue using your old project directory, and perform the following modifications:

1. Edit the pom.xml file:
   1. Remove all dependencies related to iBatis.
   2. Change the dependency on lsc-core to version 1.2.0 (or later, if a later version has been released by the time you read this)
2. Follow all the steps from the simple scenario above to edit your lsc.properties, logback.xml and sql-map-config.* files.

• If you wrote a specific Java class extending org.lsc.AbstractSycnhronize:

You should also continue using your old project directory, as in the previous case.

The parseOptions method of AbstractSynchronize has changed. The new signature is parseOptions(org.apache.commons.cli.CommandLine). You must update your code to reflect this.

If you have any trouble upgrading, don't panic.

First, have a look at your output to see if you see any errors you can fix easily.

If not, change the log priority in etc/logback.xml to DEBUG on all applicable lines, and re-try the step that was failing. If this output doesn't help you solve the problem, keep it because it will be useful to get help.

For any questions, or to get help upgrading, subscribe to the users mailing list and ask for help there. Make sure to send your configuration, exact versions (old and new) and a description of your problem. Attaching the DEBUG output is always helpful.

Alternatively, you can ask for help on IRC. See the Community page for details.