upgrade.txt

COMPASS UPGRADE DOCUMENTATION (Please see Compass JIRA for a complete change-log)
================================================================================

VERSION 2.3.0 beta 1
====================


VERSION 2.2.0 GA (6 April, 2009)
================================

NONE


VERSION 2.2.0 RC2 (26 March, 2009)
==================================

NONE

VERSION 2.2.0 RC1 (9 March, 2009)
=================================

1. Renamed the DefaultFirstLevelCache to PlainFirstLevelCache. Also changed the default first level cache to the
   NullFirstLevelCache.
2. Removed SpringSyncTransactionGpsDeviceWrapper, no need for it anymore.
3. Simplified XSEM XmlContentConverter configuration. Please refer to the XSEM XmlContent section in the reference docs.
4. Changed JSEM ContentConverter setting from 'compass.jsonContentConverter.type' to 'compass.jsem.contentConverter.type'.
5. Renamed 'compass.engine.store.tc.managed' to 'compass.engine.store.tc.type' (with values of "managed", "chm" and "csm"),
   default is still 'managed'.
6. Upgrade bundled Lucene version from 2.4.0 to 2.4.1.

VERSION 2.2.0 M2 (2 February, 2009)
===================================

1. Optimizer Refactoring:
    a. Removed AdaptiveOptimizer, it is the defualt (and only) optimizer in the system now.
    b. Removed AgressiveOptimizer. Same as the the default optimizer with maxNumOfSegments set to 1.
    c. Removed NullOptimizer. The NullOptimizer was usually used to disable scheduled optimization, but instead the
       preferred way is to set the optimizer schedule flag to false. This allows for API level optimization to still
       have meaning.
    c. Changed xsd configuration of optimizer from 'mergeFactor' to 'maxNumberOfSegments'.
    d. Changed Adaptive configuraion 'compass.engine.optimizer.adaptive.mergeFactor' to
       'compass.engine.optimizer.maxNumberOfSegments'. The setting apply to the defualt optimizer.
2. Refactored JPA NaiveJpaExtractor and implementations (Spring, JBoss, Glassfish) into the same package:
   'org.compass.gps.device.jpa.extractor'.

VERSION 2.2.0 M1 (11 January, 2009)
===================================

1. READ_ONLY_READ_COMMITTED transaction removed. CompassSession#setReadOnly() should be used instead.
2. Major refactoring perfomed in transaction management paving the way for pluggable and more robust implementations.
   What was known as transaction isolations are now knows as Transaction Processor(s). The schema file configuration
   of isolation has been renamed to processor. The readCommittedSettings has been renamed to readCommitted and should
   be placed within processors tag.
3. Change all DTD and Schema names from 2.1 suffix to 2.2 suffix.
4. Removed support for JDO.
5. Removed support for Apache OJB.
6. Removed support for Hibernate 2.
7. Added support for Compass to register a shutdown hook to be closed. By defualt, Compass registers a shutdown hook.
   In order to disable this, set compass.registerShutdownHook to false.
8. Removed the serializable tranasction processor (isolation).
9. CompassConfiguration#addMappingResover typo, changed to CompassConfiguration#addMappingResolver.


VERSION 2.1.0 GA (1 November, 2008)
===================================

1. Added new time based notation for configuration. For example: 10millis is 10 milliseconds, 10S is also 10
   milliseconds (as per SimpleDateFormat), 10s is 10 seconds, 10m is 10 minutes, 10H is 10 hours.
2. compass.engine.indexManagerScheduleInterval is now set in new time notation, this means that if it is set explicitly
   it will now be set in the default unit, which is milliseconds, and not the previous value for this setting,
   which was seconds.

VERSION 2.1.0 RC (19 October, 2008)
===================================

1. Upgraded to Lucene 2.4. Make sure to update the Lucene jars in your application as well.
2. TOKENIZED deprecated and renamed to ANALYZED. UN_TOKENIZED deprecated and renamed to NOT_ANALYZED. This applies to
   mapping definitions (annotation or xml) and programmatic ones. This follows Lucene changes to the same values.
3. Cache invalidation (of Lucene IndexReader/Searcher) is now performed in the background by a scheduled thread. In
   order to revert back to perform it syncronous with an operation (if invalidation is required), set:
   compass.engine.cacheAsyncInvalidation to false.


VERSION 2.1.0 M4 (23 September, 2008)
=====================================

NONE

VERSION 2.1.0 M3 (21 September, 2008)
=====================================

1. By default, Compass used to filter duplicates (same objects marshalled more than onces within a single root object
   object marshalling process). Now, Compass does not filter duplicates any more. A global setting: compass.osem.filterDuplicates
   can be set to true, which will revert to the old behavior. Filter duplucates can also be set on a class mapping level.
2. A full reindex is required (sorry) due to improved polymorphic queries support.


VERSION 2.1.0 M2 (July 18, 2008)
================================

NONE


VERSION 2.1.0 M1 (July 1, 2008)
===============================

1. Change all DTD and Schema names from 2.0 suffix to 2.1 suffix.
2. Upgraded Lucene version to 2.3.2 (from 2.3.1). Update the Lucene jar files.

VERSION 2.0.0 (May 10, 2008)
============================

NONE

VERSION 2.0.0 RC2 (April 21, 2008)
==================================

NONE

VERSION 2.0.0 RC1 (April 13, 2008)
==================================

1. Changed DTD location for compass cpm mappings. Change from this:
   <!DOCTYPE compass-core-mapping PUBLIC
           "-//Compass/Compass Core Mapping DTD 1.0//EN"
           "http://www.opensymphony.com/compass/dtd/compass-core-mapping.dtd">

   to this:

    <!DOCTYPE compass-core-mapping PUBLIC
            "-//Compass/Compass Core Mapping DTD 2.0//EN"
            "http://www.compass-project.org/dtd/compass-core-mapping-2.0.dtd">

2. Changed DTD location for compass configuraiton. Change from this:

    <!DOCTYPE compass-core-configuration PUBLIC
        "-//Compass/Compass Core Configuration DTD 1.0//EN"
        "http://www.opensymphony.com/compass/dtd/compass-core-configuration.dtd">

    to this:

    <!DOCTYPE compass-core-configuration PUBLIC
        "-//Compass/Compass Core Configuration DTD 2.0//EN"
        "http://www.compass-project.org/dtd/compass-core-configuration-2.0.dtd">

3. Changed DTD location for compass meta mappings. Change from this:

    <!DOCTYPE compass-core-meta-data PUBLIC
        "-//Compass/Compass Core Meta Data DTD 1.0//EN"
        "http://www.opensymphony.com/compass/dtd/compass-core-meta-data.dtd">

    to this:

    <!DOCTYPE compass-core-meta-data PUBLIC
        "-//Compass/Compass Core Meta Data DTD 2.0//EN"
        "http://www.compass-project.org/dtd/compass-core-meta-data-2.0.dtd">

4. Changed schema location for compass configuration. Change from this:

    <compass-core-config xmlns="http://www.compass-project.org/schema/core-config"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.opensymphony.com/compass/schema/core-config http://www.opensymphony.com/compass/schema/compass-core-config.xsd">

    to this:

    <compass-core-config xmlns="http://www.compass-project.org/schema/core-config"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.compass-project.org/schema/core-config http://www.compass-project.org/schema/compass-core-config-2.0.xsd">

5. Changed schema location for Spring configuration. Change from this:

    <beans xmlns="http://www.springframework.org/schema/beans"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:compass="http://www.opensymphony.com/compass/schema/spring-core-config"
           xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.opensymphony.com/compass/schema/spring-core-config http://www.opensymphony.com/compass/schema/spring-compass-core-config.xsd">

      
    to this:

    <beans xmlns="http://www.springframework.org/schema/beans"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:compass="http://www.compass-project.org/schema/spring-core-config"
           xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.compass-project.org/schema/spring-core-config http://www.compass-project.org/schema/spring-compass-core-config-2.0.xsd">


6. By default, Compass will now try to use Index type based on the actual type. For example, every formattable type
   (such as number and dates), URL, URI, and Boolean are now UN_TOKENIZED by defualt (if not explicitly specified).
7. Removed the method saveResource since save(Object obj) can also accepts a resource.
8. Compass now, by default (if not set), will use the preferable flag if to use the compound file format based on the
   actual store configured. File system based will be in compound file format, others (jdbc, coherence, gigaspaces,
   terracotta) will not use it.
9. Changed the default globabl managed-id from AUTO to NO_STORE. This means that now, when setting store="no", Compass
   won't create an internal id for it, and it will not be un-marshalled back. This is the more sensible default. To
   change back to the original setting, set setting: compass.osem.managedId to: AUTO.

VERSION 2.0.0 M3 (March 19, 2008)
=================================

1. Updated Lucene to version 2.3.1. Please update also Lucene jars.
2. The default operator when searching changed from OR to AND (which makes much more sense). Changing back to OR
   can be done by setting: compass.engine.queryParser.default.defaultOperator=OR.
3. Moved @Searchable#enableAll to @SearchableAllMetaData#enable annotation.
4. Moved @Searchable#exlcudeAliasFromAll to @SearchableAllMetaData#excludeAlias
5. Moved related all attributes (prefixed with all) from resource/class/xml-object mappings to an internal all
   attribute (sorry ...).
6. Refactored Resource and Property creation from CompassSession (#createResource, #createProperty) to a
   ResourceFactory which can be accessed from Compass instance.
7. The alias is now excluded from the all proeprty by default.

VERSION 2.0.0 M2 (February 19, 2008)
====================================

1. Compass now stores a UID for each root resource. This is a major step at some performance optimizations
   that are scheduled for 2.0. Since there is now more data in the index, a complete rebuild of the index is
   required.
2. Removed the needOptimization API from SearchEngineOptimizer. This will allow for simpler integration with
   Lucene.
3. Upgraded Compass to Lucene 2.3. Please update the lucene jar files and reindex your data.
4. Default all proeprty name changed from "all" to "zzz-all" since Lucene 2.3 introduced dependecy on lexi
   order of fields.
5. New and improved read committed transaction support. Changed the way trans log is used and configured, please
   read the reference documentation on how to configure it now.
6. Removed CopmassHitIterator. Changed CompassHits and CompassDetachedHits to support Iteratable<CompassHit>. Please
   be careful with iterating over all the result set.

VERSION 2.0.0 M1 (January 25, 2008)
===================================

1. New and improved "all" support.
    1.a all-analyzer mapping removed from resource and class mappings. Properties added to all will use their
        own analyzers when added to "all" and not use the removed all analyzer (which is the correct behviour).
    1.b untokenized properties will be added by default as untokenized to the all property. Changing to previous
        (where they were tokenized) requries adding: exclude-from-all="no_analyzed".

2. Ability to disable/enable "all" support globally using compass.property.all.enabled property. Searchable
   annotation changed its enableAll attribute to work with an enumartion and not a boolean value.

3. Renamed Resource#get to Resource#getValue. (sorry...)

4. Query Strings now support the "dot path" notation (and then some). When executing a query in the format of:
   "user.address.street:astreet", the query will automatically map to the property meta data / property and also
    add the user alias to it so it will only match users.

VERSION 1.2 (October 15, 2007)
==============================

1. Extending AbstractBasicConverter for custom converters should now override doFromString (and
   possibly doToString) instead of the previous fromString and toString. The converter code will
   remain the same.


VERSION 1.2 RC1 (September 4, 2007)
===================================

NONE


VERSION 1.2 M3 (August 3, 2007)
===============================

1. New HibernateGpsDevice with mcuh improved features. Hibernate3GpsDevice, Hibernate2GpsDevice, and
   SpringHibernate3GpsDevice refactored to a different package with "dep" at the end.

VERSION 1.2 M2 (June 25, 2007)
==============================

1. Lucene version upgraded to 2.2. Make sure to updated Lucene jars with the new versions.

VERSION 1.2 M1 (May 11, 2007)
=============================

1. Lucene version upgraded to 2.1 with Compass support for lockless commits. Make sure to update the Lucene jars
   with the new version. A full reindex of the data is required.
2. All references and settings for transaction commit locks have been removed thanks to lockless commits.
3. compass.transaction.lockDir removed and no longer used. The lock by default is now stored in the index directory.


VERSION 1.1 (February 15, 2007)
===============================

NONE

VERSION 1.1 RC1 (January 19, 2007)
==================================

1. CompassSearchController Spring MVC search callbacks removed. The search operation refactored to a
   utility class called CompassSearchHelper (with the same callbacks) which can be injected into the
   search controller.

VERSION 1.1 M3 (November 28, 2006)
==================================

1. Component max-depth default changed to 1 (from 5). Most cyclic component mappings are used
   for bi-directional relationship, where max-depth of 1 is fine. For tree based cyclic relationships
   max-depth should be set to an appropiate value. This change will result in much less memory consumption
   by compass.
2. Empty Collections/Arrays (size = 0) are returned as empty arrays / collections now, and not as nulls.

VERSION 1.1 M2 (September 27, 2006)
===================================

1. OSEM setting compass.managedId.index changed to compass.osem.managedId.index .
2. Removed Resource#setAlias.


VERSION 1.1 M1 (August 25, 2006)
================================

1. Removed CompassTermInfo and CompassSession API supporting it, and added it to 
   LuceneHelper. It now uses actual Lucene classes.


VERSION 1.0.0 (July 23, 2006)
=============================

1. When using Spring and Compass Gps, each device should be wrapped with
   org.compass.spring.device.SpringSyncTransactionGpsDeviceWrapper for better transaction handling.

VERSION 0.9.1 (May 27, 2006)
============================

No upgrade steps required to use 0.9.1.


VERSION 0.9.0 (Apr 17, 2006)
============================

1. Package name changed back to org.compass from org.compassframework.
   Due to the move to Open Symphony, the name Compass is back, without the Framework part.
2. DTD Location changed.
   http://static.compassframework.org/dtd/ prefix should now state: http://www.opensymphony.com/compass/dtd.
   The -1.0 version was removed.
3. Converters Support Enhancements and Changes.
   a) Removed converter-param from all the different mapping definitions in the Compass Core DTD.
   b) The converter element no longer points to an implementation class of the Converter class. Instead, it
      acts as a lookup name for a Converter (which was registered under the name).
   c) Since the converter-param was mostly used for formatting Dates and Numbers, the format attribute was
      added to the DTD, allowing for quick setting of the format, without going through the hassle of 
      defining a new Converter and registering it. Note, that it must be set only on formatting converters.
   d) Old way of registering new converters still works (CompassConfiguration#registerConverter).
   e) You can now configure new converters using Compass configuration settings. The converter setting is
      compass.converter.[converter name].[settings]. For example, to register a new DateConverter, two settings
      must be set, compass.converter.mydate.type=date, and compass.converter.mydate.format=yyyy-MM-dd. Now,
      you can use the mydate converter lookup name in the converter mapping attribute.
   f) You can now override default converters that comes with compass. They are registered under Compass
      default names. For example, to change the format for all Dates, simply provide the setting
      compass.converter.date.format=yyyy-MM-dd.
   For more information, please check the reference documentation.
4. Component and Reference mapping ref-alias is no longer required. Under certain conditions, Compass can infer
   the class mapping associated with the class property return type.
5. col-class mapping is no longer required and removed from the mapping definitions.
6. compass.engine.store.jdbc.dialect is no longer required when using Jdbc. 
   Compass will try to auto-detect the correct Dialect.
7. compass.transaction.managerLookup is no longer required when using JTA. 
   Compass will try to auto-detect it based on the JTA implementation used.
8. The setting for compound file format was wrongly named, changed to: compass.engine.useCompoundFile.
9. A new XML configuration based on XML schema is available. It is now the preferred way to configure Compass.

VERSION 0.8.1 (Jan 22, 2006)
============================

None.

VERSION 0.8.0 (Jan 02, 2006)
============================

1. Spring Transaction Manager.
   If using compass with a spring transaction manager (and probably using SpringSyncTransactionFactory),
   the transaction manager must be injected to the LocalCompassBean.
   The transactionManager property was removed from the CompassIndexController and CompassSearchController,
   now there is only one place to define the transactionManager that compass will integrate with, and that
   is the transactionManager of the LocalCompassBean.
2. CompassGps index Operation.
   When performing the index operation, it is very important in the new version NOT to perform it within an
   already running transaction. For LocalTransactionFactory, no outer LocalTransaction should be started.
   For JTATransactionFactory, no JTA transaction must be started, or no CMT transaction defined for the method
   level. For SpringSyncTransactionFactory, no spring transaction should be started before, and the executing
   method should not be wrapped with a transaction (using transaction proxy).

VERSION 0.7.0 (Dec 22, 2005)
============================

1. Actual Index directory moved to index sub directory.
   If specifying a file system location for the index, the sub indexes will be created under a directory
   called index (within the configured path). If you wish to use the same index from version 0.6.2, it is
   possible, but you will need to manually create the index directory, and move all the other directories
   into it.


VERSION 0.6.2 (Nov 22, 2005)
============================

1. Index control moved from Compass.
   A new interface called SearchEngineIndexManager will now handle all index related operations (like
   delete, verify). It is reachable from the Compass instance.
2. Minor API change in CompassDetachedHits.
   The toHits, toDatas, and toResources, were change and the to part was changed to get, for simpler usage
   in scripting langs (or JSP's).
3. CompassGps index functionality changed.
   CompassGps no longer has the deleteIndexBeforeIndex property, the two implementation will now gracefully
   replace the online index with the content of the index operation. Please consult the documentation for
   more information.

VERSION 0.6.1 (Sep 30, 2005)
============================

1. The mapping definition name excludeFromAll is changed to exclude-from-all.
2. The mapping definition name managedId is changed to managed-id.
3. CompassQueryBuilder#eq changed to CompassQueryBuilder#term
4. CompassQueryBuilder#eqAlias changed to CompassQueryBuilder#alias
5. CompassHits refactored to CompassHitsOperations, CompassHits and CompassDetachedHits. A better separation
   between the notion of hits (CompassHits) which can be used within a transactional context, and detached
   hits (CompassDetachedHits), that can be used outside of a transactional context. The CompassHitsOperations
   interface is used for operations that can be done on both hits. Also, several method were renamed/removed
   as per the general contract of hits (i.e. getScore(int n) removed and only score(int n) left).
6. The setting compass.engine.optimizer changed to compass.engine.optimizer.type.


VERSION 0.6 (Sep 30, 2005)
==========================

1. Package name changed from org.compass to org.compassframework.
2. DTD location changed to http://static.compassframework.org/dtd/compass-core-mapping.dtd.
3. The settings for the analyzer used was changed. Compass can now be configured with multiple
   analyzers, and they can be referenced. The new setting looks like: compass.analyzer.(analyzer name).*,
   with two internal analyzers called default and search. Please read more at the Search Analyzer section
   in the documentation.
4. Removed the DefaultCompassGps, which had two compass instances with the confusing names of compass
   and batchCompass. There will be two implementation of CompassGps now: a) DualCompassGps: Will act the
   same as DefaultCompassGps, but will have better names for the two compass instances: indexCompass and
   mirrorCompass. b) SingleCompassGps: Based on the fact that 0.6 version allows to set the transaction
   isolation when starting a new transaction, it will only have a single Compass instance. When indexing,
   the transaction will begin with the batch_insert transaction isolation, and when mirroring, using the
   configured transaction isolation. It is a simpler solution which should work in most cases, and have
   better memory performance.

VERSION 0.5
===========

None.

VERSION 0.4
===========

Initial release