====== Upgrading from 1.1.* to 1.2 ======

===== Differences between 1.1 and 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.

==== Generation is no longer necessary ====

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. 

==== LSC-sample no longer exists ====

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 are no longer required ====

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.

==== db2ldap configuration has been simplified ====

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.

==== The logging system and configuration has changed ====

//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.

===== Upgrading =====

==== Simple scenario ====

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:

  - [[http://tools.lsc-project.org/files|Download]] the latest 1.2.x //dist// archive and uncompress it. The result is the main LSC directory for 1.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//.
  - Edit the new **lsc.properties** file:
    - Delete //taskType// properties lines (like //lsc.tasks.MyTask.taskType = db2ldap//)
    - Delete //object// properties lines (like //lsc.tasks.MyTask.object = org.lsc.objects.pPerson//)
    - Replace all //bean// properties values (like //lsc.tasks.MyTask.bean = org.lsc.beans.inetOrgPersonBean//) with the value **org.lsc.beans.SimpleBean**.
  - Open your old **log4j.properties** file, and copy it's whole content into the [[http://logback.qos.ch/translator/|log4j to logback translator]]. Copy and paste the result into the file **logback.xml** in the new LSC directory, under //etc//.
  - Edit this last file, //etc/logback.xml//:
    - Replace all occurrences of //org.lsc.utils.LocalizedJndiModificationsLayout// with //org.lsc.utils.output.LdifLayout//
    - Replace all occurrences of //org.lsc.utils.log4j.csv.CsvLayout// with //org.lsc.utils.output.CsvLayout//
    - Replace all occurrences of //ConversionPattern>// with //pattern>//
    - If you have a pattern with the convertion word //l// (the letter L) replace it with //L//
    - If you have a rollingPolicy you have to specify a configuration ofr it (see : [[http://logback.qos.ch/codes.html#tbr_fnp_not_set|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:
  - 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.
  - 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///.
  - Edit your new //etc/lsc.properties//:
    - Replace the task.srcService property (like //lsc.tasks.MyTask.srcService//) with **org.lsc.service.SimpleJdbcSrcService**.
    - 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///.
  - 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:

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

(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//).

==== Complex scenario ====

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 **[[:documentation:1.2:configuration:syncoptions|syncoptions]]**.

  * **If you modified a generated //bean//**:

It is preferable to move any specific code from your bean to **[[:documentation:1.2:configuration:syncoptions|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:

  - Edit the **pom.xml** file:
     - Remove all dependencies related to **iBatis**.
     - 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)
  - 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.

===== Troubleshooting =====

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 [[http://lists.lsc-project.org/listinfo/lsc-users|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|Community]] page for details.