| Apache Cayenne Upgrade Information |
| ================================== |
| |
| IMPORTANT: be sure to read all notes for the intermediate releases between your |
| current release and the release you are upgrading to. |
| ------------------------------------------------------------------------------- |
| |
| UPGRADING TO 4.2.M1 |
| |
| * Per CAY-2520 ObjectId can't be instantiated directly, ObjectId.of(..) methods should be used. |
| E.g. ObjectId.of("Artist", 1) instead of new ObjectId("Artist", 1). |
| |
| * Per CAY-2523 SelectQuery was deprecated. Use ObjectSelect instead. |
| |
| * Per CAY-2525 OpenBase adapter was deprecated. |
| |
| * Per CAY-2467 Property class is replaced with a type-aware Property API, it's mostly backwards compatible. |
| To take advantage of this new API you should regenerate code via Modeler ("Tools" -> "Generate Classes") or cgen tools. |
| |
| * Per CAY-2563 SQLSelect.scalarQuery(Class<T>, String) and SQLSelect.scalarQuery(Class<T>, String, String) methods |
| were deprecated. |
| |
| * Per CAY-2585 SQLSelect.scalarQuery(String sql), SQLSelect.scalarQuery(String sql, String dataMapName), |
| SQLSelect.scalarQuery(String sql, Class<?> firstType, Class<?>... types), |
| SQLSelect.scalarQuery(String sql, String dataMapName, Class<?> firstType, Class<?>... types) and |
| SQLSelect.params(String name, Object value) were deprecated. |
| |
| UPGRADING TO 4.1.M3 |
| |
| * Per CAY-2514 SERVER_CONTEXTS_SYNC_PROPERTY default value was set to false. |
| |
| UPGRADING TO 4.1.M2 |
| |
| * Per CAY-2438 DataChannelFilter filter was deprecated and two new independent filters are introduced: |
| DataChannelSyncFilter and DataChannelQueryFilter. |
| |
| * Per CAY-2400 Cayenne-DBCP2 integration was deprecated |
| |
| * Per CAY-2377 All code deprecated in Cayenne 4.0 was removed, please review your code before upgrading. |
| |
| * Per CAY-2372 three new modules extracted from Cayenne core. No changes to the packages or api have been made, |
| so only include additional modules to your project if you use them. |
| |
| - cayenne-web module contains all logic related to bootstrapping Cayenne inside a servlet container. |
| WebModule is autoloaded, so you shouldn't add it to runtime explicitly any more. |
| - cayenne-osgi module contains OSGi related functionality. |
| - cayenne-rop-server ROP server part. |
| |
| UPGRADING TO 4.1.M1 |
| |
| * Per CAY-2351 Minimum supported Java version is now Java 8. There is no options to use Cayenne 4.1 with earlier |
| versions, you should use 4.0 version if Java 7 is required by your project. |
| |
| * Per CAY-2345 Velocity replaced with Cayenne own template engine by default in cayenne-server, |
| this should be transparent in almost all cases, however if you relied on advanced Velocity |
| features in SQLTemplate you can include auto-loaded cayenne-velocity module and keep using Velocity, |
| no other actions required. |
| |
| * Per CAY-2335 ServerRuntime by default will fail to load projects in case of version mismatch. |
| You have two options: |
| - update project files via opening them in Cayenne Modeler |
| - if you are unable to do so you can use new cayenne-project-compatibility module, |
| to enable it simply add it as a dependency in Maven (or any other build system you use), however |
| this module can support only versions created by Cayenne 3.1 or later. |
| |
| * Per CAY-2330 Field-based data objects are introduced and enabled by default. |
| Your existing code will continue to work, but in order to get benefits from this feature you should |
| regenerate code via Modeler ("Tools" -> "Generate Classes") or cgen tools in Maven/Ant/Gradle plugins. |
| Also note that serialization format of old data objects have changed, make sure you don't use serialization |
| form to store your objects. |
| |
| UPGRADING TO 4.0.B1 |
| |
| * Per CAY-2302 postcommit module and all it's internals renamed to commitlog. |
| Most important change is the new @CommitLog annotation which should be used instead of @Auditable, |
| this change is backward incompatible and most likely for you to miss as IDE won't give you a hint. |
| Please keep in mind that new @CommitLog annotation is used only by commitlog module. |
| Deprecated functionality in lifecycle module still depends on @Auditable annotation. |
| |
| Here is list of steps you should do in order to update your code: |
| - include cayenne-commitlog module into your project (i.e. add dependency to your pom.xml) |
| - remove cayenne-lifecycle (and cayenne-postcommit if you have it) module from your project |
| - switch usages of @Auditable to @CommitLog |
| - change usages of renamed classes, here is two classes most likely used by your code: |
| PostCommitListener -> CommitLogListener |
| PostCommitModuleBuilder -> CommitLogModuleExtender |
| - fix all imports for renamed packages: |
| org.apache.cayenne.lifecycle.postcommit -> org.apache.cayenne.commitlog |
| org.apache.cayenne.lifecycle.changemap -> org.apache.cayenne.commitlog.model |
| - change CommitLogModuleExtender methods: |
| auditableEntitiesOnly() -> commitLogAnnotationEntitiesOnly() |
| build() -> module() |
| |
| * Per CAY-2280 Cayenne migrated from commons-logging to SLF4J. |
| Here is options you have to upgrade your project accordingly: |
| 1) Migrate your logging to SLF4J. Please see https://www.slf4j.org for documentation about |
| inclusion into your project logging backend of you choice. |
| |
| 2) Other option is to use commons-logging over SLF4J and keep all logging compatible with previous Cayenne versions. |
| In order to do so you need: |
| - remove commons-logging dependency if you have it |
| - add to your project slf4j-jcl dependency |
| |
| As a part of this change classes CommonsJdbcEventLogger and FormattedCommonsJdbcEventLogger |
| were renamed to Slf4jJdbcEventLogger and FormattedSlf4jJdbcEventLogger respectively. |
| Internally they are using now org.apache.cayenne.log.JdbcEventLogger interface as a logger name. |
| |
| * Per CAY-2278 Packages org.apache.cayenne.lifecycle.audit and org.apache.cayenne.lifecycle.changeset where deprecated. |
| Please use instead cayenne-commitlog module and its new @CommitLog annotation. |
| |
| Weighted graph sorter moved to cayenne-server into org.apache.cayenne.ashwood package. |
| |
| Packages org.apache.cayenne.lifecycle.changemap and org.apache.cayenne.lifecycle.postcommit |
| where moved to the new cayenne-commitlog module. |
| |
| Please change your code accordingly (see also notes above for CAY-2302). |
| |
| * Per CAY-2277 ClientRuntime created with ClientRuntimeBuilder, direct instantiation of |
| ClientRuntime is deprecated. Also whole ClientLocalRuntime class is deprecated, use instead |
| ClientRuntimeBuilder.local() method. |
| |
| * Per CAY-2262 Client modules are now auto-loaded by default to turn off auto-loading use |
| ClientRuntimeBuilder.disableModulesAutoLoading() method. |
| |
| List of client modules: |
| - cayenne-client |
| - cayenne-client-jetty |
| - cayenne-protostuff (it also supports auto-loading by ServerRuntimeBuilder) |
| |
| Also new modules are extracted from the existing one and should be added to your pom.xml if the corresponding |
| functionality is used by your project: |
| - cayenne-cache-invalidation (was part of cayenne-lifecycle) |
| - cayenne-commitlog (was part of cayenne-lifecycle) |
| |
| * Per CAY-2259 Cache invalidation module refactored to provide new functionality and better align with |
| new module autoloading functionality. Here is list of changes: |
| - Package org.apache.cayenne.lifecycle.cache renamed to org.apache.cayenne.cache.invalidation. |
| - CacheInvalidationModuleBuilder renamed to CacheInvalidationModuleExtender and its method build() |
| renamed to module(). |
| - InvalidationFunction returns CacheGroupDescriptor instead of simple String with cache group name, |
| so you need to change your custom functions accordingly. |
| |
| * Per CAY-2268 DI methods for binding ordered lists, introduced in 4.0.M3 where changed: |
| - method after() replaced by explicit addAfter(), addAllAfter() |
| - method before() replaced by insertBefore(), insertAllBefore() |
| |
| * Per CAY-2258 Injection of List and Map are made type-safe, as a result small incompatibilities are introduced. |
| If you are using following methods: |
| - bindMap(String bindingName) |
| - bindList(String bindingName) |
| you should change them to corresponding type-safe versions: |
| - bindMap(Class<T> valueType, String bindingName) |
| - bindList(Class<T> valueType, String bindingName) |
| Also if you are using DI Keys like Key.get(Map.class, "bindingName") or Key.get(List.class, "bindingName") |
| you should use new corresponding factory methods Key.mapOf(MapValues.class, "bindingName") |
| and Key.listOf(ListValues.class, "bindingName"). |
| Additionally new API allows you to bind Lists and Maps without using names: |
| - binder.bindList(SomeUniqueType.class).add(...); |
| - @Inject List<SomeUniqueType> list; |
| |
| * Per CAY-1873 and CAY-2266 Cache and remote notification configuration was moved from Modeler into |
| runtime DI settings. To set custom cache size, you should use custom module like this: |
| Module module = binder -> { |
| ServerModule.setSnapshotCacheSize(binder, 20000); |
| }; |
| Or you can use cmd line arg: -Dcayenne.DataRowStore.snapshot.size=20000 |
| |
| If you have used remote notifications, you should include one of the following modules into your project: |
| - cayenne-jgroups |
| - cayenne-jms |
| - cayenne-xmpp |
| For maven users this can be easily done by adding dependency to pom.xml: |
| <dependency> |
| <groupId>org.apache.cayenne</groupId> |
| <artifactId>cayenne-jgroups</artifactId> |
| <version>4.0.M6</version> |
| </dependency> |
| |
| Module will be autoloaded and remote notifications enabled, so only thing you need is to provide configuration. |
| Custom DI module should be used for that, e.g. for JGroups: |
| Module module = binder -> { |
| JGroupsModule.contributeMulticastAddress(binder, MCAST_ADDRESS); |
| JGroupsModule.contributeMulticastPort(binder, MCAST_PORT)); |
| }; |
| |
| |
| * Per CAY-2256 Fix for CAY-2146 was reverted, as it appears that we can't reliably deduce whether |
| relationship is optional or not. So in case of mandatory relationships in vertical inheritance |
| you should perform manual validation before insert by using "prePersist" callback in your |
| object (you can create it in the Cayenne Modeler) or by overriding "validateForSave" method. |
| |
| |
| UPGRADING TO 4.0.M5 |
| |
| * Per CAY-2186 DerbyPkGenerator switched from AUTO_PK_TABLE to sequence-based PK generator |
| If you relied in anyway on AUTO_PK_TABLE usage in derby, you should change your code. |
| |
| * Per CAY-2228 Support for multiple cache groups has been removed from caching and query API |
| as none of the modern providers supports it. If you relied on this feature you should |
| implement it by yourself or change caching provider |
| |
| * Per CAY-1980 "maven-cayenne-modeler-plugin" renamed to "cayenne-modeler-maven-plugin" |
| |
| * Per CAY-2225 CacheInvalidationFilter has been changed to support custom invalidation rules, |
| in addition to the rule based on @CacheGroups annotation. |
| If you have used it previously, you should change its binding to runtime from direct binding in |
| a custom module to a module built by CacheInvalidationModuleBuilder. |
| |
| * Per CAY-2212 cdbimport tool revisited once again, so configuration of Maven plugin should be changed. |
| - "maven-cayenne-plugin" is deprecated, please switch to "cayenne-maven-plugin" |
| - <reverseEngineering> tag replaced with <dbimport> tag |
| - new <dataSource> tag introduced that should enclose all connection properties: |
| 1. <driver> |
| 2. <url> |
| 3. <user> |
| 4. <password> |
| |
| - top level properties moved to <dbimport>: |
| 1. <defaultPackage> |
| 2. <forceDataMapCatalog> |
| 3. <forceDataMapSchema> |
| 4. <meaningfulPkTables> |
| 5. <namingStrategy> |
| 6. <stripFromTableNames> |
| 7. <usePrimitives> |
| |
| - Java 8 java.time.* types are now used by default in cdbimport (and in "Reengineer Database Schema" tool in Modeler) |
| This can be controlled by <useJava7Types> property in <dbimport> (or checkbox in Modeler). |
| |
| - For Ant users: cayenne-tools.jar split into two parts: |
| 1. cayenne-ant.jar for Ant tasks |
| 2. cayenne-cgen.jar for class generation functionality (required only for cgen task) |
| |
| |
| * Per CAY-2166, Cayenne supports auto-loading of DI modules. There are a few changes worth mentioning: |
| - Service override policies. In the previous 4.0 milestones custom modules would override "builder" modules |
| (i.e. implicit modules that wrap around various customizations made in response to the builder method calls). It |
| seemed logical to reverse this order, and let builder modules override custom modules. As the builder is |
| invoked explicitly when the stack assembly is performed, while modules can be written without any knowledge of the |
| final stack. |
| - Module Renaming and Explicit Loading of Modules. If you see compile errors (class not found for CayenneJodaModule, |
| CayenneJava8Module), just remove explicit loading of those modules. They will be auto-loaded if they are on classpath. |
| If you explicitly turn off auto-loading, use the new names for these modules: JodaModule and Java8Module. |
| |
| * Per CAY-2164, creating a ServerRuntimeBuilder is done via a static method on ServerRuntime ("ServerRuntime.builder()"). |
| The previous style (ServerRuntimeBuilder.builder()) is deprecated and will soon be removed, so you should replace it |
| with the new API. |
| |
| UPGRADING TO 4.0.M4 |
| |
| * Per CAY-2133, LegacyObjectNameGenerator is no longer provided, as it wasn't possible to maintain it in a fully backwards- |
| compatible manner. Embrace the new naming scheme, or provide your own ObjectNameGenerator if you absolutely need the |
| old names. |
| |
| * Per CAY-2125 we no longer inject SchemaUpdateStrategy directly. Instead SchemaUpgradeStrategyFactory is injected. |
| If you have your own modules with SchemaUpdateStrategy injection, it will be ignored. So please review your |
| DI code and update it to use SchemaUpgradeStrategyFactory (or likely its subclass). |
| |
| * Per CAY-2060 4.0.M4 changes the way queries are stored in the mapping files, so all existing *.map.xml files should be upgraded. |
| To do that open each of your existing projects in the new CayenneModeler. Agree to perform an upgrade when asked. |
| |
| Also EntityResolver.getQuery(String) method is removed. If you relied on it, consider switching to MappedSelect or MappedExec query, or if you absolutely need to get a hold of specific query, use EntityResolver.getQueryDescriptor(String).buildQuery(). |
| |
| * Per CAY-2065 ROPHessianServlet has been discarded in favor of new implementation called ROPServlet, |
| so if you were using org.apache.cayenne.configuration.rop.server.ROPHessianServlet in your web.xml configuration, |
| you must change it to org.apache.cayenne.rop.ROPServlet |
| |
| * Per CAY-2118 we stopped a bunch of deprecated keys in cdbimport configuration, and also removed the ability to set |
| properties of "reverseEngineering" config object at the top level of configuration. So you will always need |
| <reverseEngineering></reverseEngineering> tag in Maven (but not Ant) to setup any DB filtering. Removed top-level |
| configuration keys: |
| |
| 1. catalog |
| 2. schema (also schemaName) |
| 3. excludeTables |
| 4. includeTables |
| 5. procedurePattern |
| 6. tablePattern |
| 7. importProcedures |
| 8. meaningfulPk |
| 9. overwrite |
| |
| UPGRADING TO 4.0.M3 |
| |
| * Per CAY-2026 minimal Java version is now 1.7. If you are still need Java 1.6, you can use Cayenne 3.1 or 4.0.M2 until your |
| application is able to upgrade. |
| |
| * We no longer add @Deprecated annotation to generated String property names in entity superclasses. |
| Instead String property names inclusion |
| became optional, controlled with "createPropertyNames" flag in cgen ("false" by default). Also a similar option |
| was added to Advanced Type of CayenneModeler class generation dialog. |
| Note if you have references to @Deprecated String properties and you run cgen without "createPropertyNames" flag, |
| there will be errors. Reference Jira: CAY-1991 |
| |
| * Per CAY-2008, CAY-2009 we got rid of org.apache.cayenne.conn.PoolManager and associated classes that made up a |
| pooling DataSource. A replacement is non-blocking DataSource under org.apache.cayenne.datasource (PoolingDataSource, ManagedPoolingDataSource), |
| best assembled using org.apache.cayenne.datasource.DataSourceBuilder. |
| |
| * Per CAY-2012 API for ObjectSelect and SelectById queries were changed to remove "reset" functionality. Methods like 'where', 'prefetch', |
| 'orderBy' that would previously reset the corresponding option state now work as "append". Methods that would previously append to the |
| option state were removed as redundant. Please revisit your code if you previously relied on the reset behavior. |
| |
| * If you are using DBCPDataSourceFactory, you will need to take a few steps to upgrade: |
| |
| - Per CAY-2025 and CAY-2026, DBCPDataSourceFactory is now based on DBCP2 (which is required under Java 1.7 and newer). |
| - Check your DBCP properties file to ensure it uses property names supported by DBCP. |
| (In the past Cayenne would require prefixing those properties with 'cayenne.dbcp.'. If you still have that prefix, remove it). |
| - To use DBCPDataSourceFactory, you will now have to explicitly include an extra Cayenne module, as it is no longer in cayenne-server. |
| E.g. if you are using Maven: |
| |
| <parent> |
| <groupId>org.apache.cayenne</groupId> |
| <artifactId>cayenne-dbcp2</artifactId> |
| <version>4.0.M3</version> |
| </parent> |
| |
| |
| UPGRADING TO 4.0.M2 |
| |
| * Note that 3.2 line of development was renamed to 4.0. So 4.0.M2 is a straight descendant of |
| 3.2M1. |
| |
| * org.apache.cayenne.map.naming.SmartNamingStrategy was replaced with org.apache.cayenne.map.naming.DefaultNameGenerator. If you |
| mentioned SmartNamingStrategy explicitly in your Maven or Ant configs, make sure you rename it. Since this was/is the default, |
| chances are that you didn't. |
| |
| * Minimal required JDK version is now 1.6 (both for modeler and runtime). This is a pretty conservative |
| requirement, considering that Java 1.6 has been EOL'd by Oracle on Feb 2013. |
| |
| * Managing listeners in the Modeler is counterproductive and confusing, |
| so support for them was removed from the Modeler per CAY-1842. If you have |
| any listeners in the model, delete them from XML, and start using annotations, |
| and register them in runtime: |
| |
| runtime.getDataDomain().addListener(myListener); |
| |
| * Cayenne.objectForSelect(Select) that was present in 3.2M1 was replaced with ObjectContext.selectOne(Select). |
| |
| * In-memory expression eval (Expression.match/Expression.evaluate) will now return true when matching Persistent |
| with ObjectId or Number or String (if those correspond to a given object's ObjectId). Also 2 objects in 2 different |
| ObjectContexts will match even if they have differing local changes. Only their ObjectIds are compared. |
| See CAY-1860 for details. |
| |
| * ResultIterator was moved to org.apache.cayenne to make it available on both server and client. When you upgrade |
| related iterator code, make sure to check ResultIterator improvements (e.g. it implements Iterable, it is no |
| longer limited to DataRows and can fetch objects just as easy, it no longer requires catching checked exceptions). |
| Also check ObjectContext.iterate(..) method. |
| |
| * Transaction management was refactored significantly: |
| |
| * External transactions are no longer configured in the Modeler. Instead they are provided as a DI property |
| defined in Constants.SERVER_EXTERNAL_TX_PROPERTY. |
| |
| * TransactionDelegate is no longer present. Similar functionality can be achieved by writing a decorator for |
| Transaction interface and using a custom TransactionFactory to decorate standard transactions. |
| |
| * If your code relied on static methods Transaction.externalTransaction() or Transaction.internalTransaction() for |
| manual tx management, use constructors of ExternalTransaction and CayenneTransaction classes instead. |
| |
| * When switching to ServerRuntimeBuilder, users of multi-config projects may erroneously assume it has the same |
| behavior as 3.1 ServerRuntime in assigning domain name to the resulting merged project. Which is to use the |
| name of the last project config. We are trying to move away from this behavior, so ServerRuntimeBuilder |
| will only use config name if there's only one config and no override. Otherwise it will use the override, |
| or if not set - "cayenne" as the default name. Reference Jira: CAY-1972 |
| |
| |
| |
| UPGRADING TO 3.1B1 |
| |
| * In an attempt to better organize DI configuration and ultimately make it easier to understand, |
| all properties and DI collection keys were placed in a single Constants interface. The property and key String |
| values were changed to follow a single convention. Please refer to https://issues.apache.org/jira/browse/CAY-1665 |
| for mapping between the old and the new names. |
| |
| If you are upgrading from the earlier 3.1 releases, please change your code and runtime parameters accordingly. |
| 3.0 users may still review the new property names as some of them existed prior to DI. |
| |
| UPGRADING TO 3.1M3 |
| |
| * DataMap listeners are no longer supported. Global listeners registered through |
| annotations API can be used instead. E.g.: |
| |
| public class SomeListener { |
| @PrePersist |
| public void onPrePersist(Object object) { |
| // callback method |
| } |
| } |
| |
| To register listener class use following API: |
| |
| runtime.getChannel().getEntityResolver().getCallbackRegistry().addListener(listenerInstance); |
| |
| Note that DataMap listeners entries from old *.map.xml files will be ignored. |
| |
| |
| UPGRADING TO 3.1M1 |
| |
| The most essential change in Cayenne 3.1 is a new Dependency-Injection (DI) based |
| bootstrap and configuration mechanism, which is not backwards compatible with 3.0. |
| Read on to learn about specific areas that require attention when upgrading your |
| application. |
| |
| * Upgrading 3.0.x mapping files: Open each of your existing projects in the new |
| CayenneModeler. Agree to perform an upgrade when asked. Note that Cayenne |
| 3.1 only supports one DataDomain per project, so if multiple domains existed in |
| the project, you'll end up with multiple project files after the upgrade. Each |
| will require instantiation of a separate ServerRuntime in the code. |
| |
| * Upgrading 2.0.x and earlier mappings files: Note that CayenneModeler |
| 3.1 won't be able to upgrade projects created with a Modeler older than 3.0. To |
| upgrade older projects do it in two steps - download Cayenne 3.0, and perform an |
| upgrade with 3.0 CayenneModeler. After that perform a second upgrade from 3.0 to |
| 3.1. |
| |
| * Cayenne runtime bootstrap: In 3.1 all classes under "org.apache.cayenne.conf" |
| package were removed, superseded by dependency injection (DI) based configuration, |
| with main classes located under "org.apache.cayenne.configuration" and its |
| subpackages. E.g. to instantiate the Cayenne stack in 3.1 you would do |
| something like that: |
| |
| ServerRuntime cayenneRuntime = new ServerRuntime("cayenne-UntitledDomain.xml"); |
| |
| To obtain a new ObjectContext, the following API is used: |
| |
| ObjectContext context = cayenneRuntime.getContext(); |
| |
| * No static configuration singleton: Cayenne 3.1 completely gets rid of a (previously |
| optional, but widely used) "Configuration.sharedConfiguration" singleton. This |
| change was done to acknowledge the fact that single configuration per application |
| is just a special case, and generally user can instantiate as many configurations |
| (or ServerRuntime's in 3.1 terms) as appropriate. This however means that the |
| users must now decide themselves where in their application it is appropriate to |
| store ServerRuntime instance (or instances). E.g. it can be stored as an attribute |
| of ServletContext (check out "org.apache.cayenne.configuration.web.CayenneFilter" and |
| "org.apache.cayenne.configuration.web.WebUtil"), reside in a user's favorite dependency |
| injection container (e.g. Spring), or even be saved in a user's own static singleton |
| variable. |
| |
| * No static DataContext creation methods: Methods like DataContext.createDataContext() |
| were relying on static configuration singleton, which was removed (see above). Use |
| ServerRuntime instance methods to create context instances. |
| |
| * Webapp configuration changes: "org.apache.cayenne.conf.WebApplicationContextFilter" |
| was replaced by "org.apache.cayenne.configuration.web.CayenneFilter". See CayenneFilter |
| javadocs for details on of the init parameters. |
| |
| * ROP Server configuration changes: "org.apache.cayenne.remote.hessian.service.HessianServlet" |
| was replaced by "org.apache.cayenne.configuration.rop.server.ROPHessianServlet". See |
| ROPHessianServlet javadocs for details on its init parameters. |
| |
| * ROP Client configuration changes: There is now a special DI "runtime" object - |
| "org.apache.cayenne.configuration.rop.client.ClientRuntime", so client connection |
| and channel can be (optionally) managed via DI, with connection parameters |
| specified as properties. E.g.: |
| |
| Map<String, String> properties = new HashMap<String, String>(); |
| properties.put(ClientModule.ROP_SERVICE_URL, "http://localhost:8080/tutorial/cayenne-service"); |
| properties.put(ClientModule.ROP_SERVICE_USER_NAME, "cayenne-user"); |
| properties.put(ClientModule.ROP_SERVICE_PASSWORD, "secret"); |
| |
| ClientRuntime runtime = new ClientRuntime(properties); |
| ObjectContext context = runtime.getContext(); |
| |
| The advantage of this approach in that all the client stack objects are managed |
| by the DI container and a user can customize/override various pieces. |
| |
| * Deprecated API removal: All API deprecated as of 3.0 is removed. This may require |
| some code cleanup. Since 3.0 javadocs for suggested replacements. Also if custom |
| class generation templates are used, doublecheck that they do not reference removed |
| EntityUtil methods, which were replaced by variables placed directly into Velocity context. |
| |
| * Custom DbAdapter / DbAdapterFactory: The interface used by Cayenne to allow custom |
| DbAdapters to be auto-detected with AutoAdapter has changed from |
| org.apache.cayenne.dba.DbAdapterFactory to org.apache.cayenne.configuration.DbAdapterDetector. |
| Note that now a custom implementation can rely on Cayenne DI to obtain Cayenne |
| dependencies via @Inject annotation. To register a custom implementation with |
| Cayenne DI container, one might do this in the custom DI module: |
| |
| ... |
| public void configure(Binder binder) { |
| ... |
| binder.bindList(DbAdapterFactory.class).add(new MyDbAdapterDetector()); |
| } |
| |
| * Custom DataSourceFactory: The interface used by Cayenne to load custom DataSource |
| factories has changed from "org.apache.cayenne.conf.DataSourceFactory" to |
| "org.apache.cayenne.configuration.DataSourceFactory". This new interface must be |
| implemented by the custom factories. Note that now a custom implementation can |
| rely on Cayenne DI to obtain Cayenne dependencies via @Inject annotation. |
| |
| * Replaced JNDI preferences hack with runtime properties: "JNDI hack", as it was |
| known prior to 3.1, allowed to define a named database connection using CayenneModeler, |
| and then Cayenne would read this connection information from Modeler preferences |
| and use it as a failover for JNDI DataNodes. The problem with this is that it |
| required CayenneModeler and HSQLDB jars on the application classpath, and also that the |
| preferences database was prone to data corruption. In 3.1, preferences hack is no |
| longer available. Instead JNDI (or really any other type of DataSourceFactory) |
| can be overridden via runtime properties (or by redefining DataSourceFactoryLoader |
| via DI). See org.apache.cayenne.configuration.server.PropertyDataSourceFactory javadocs for |
| details. Here are some simple examples: |
| |
| -Dcayenne.jdbc.url=jdbc://urloverride |
| -Dcayenne.jdbc.driver=com.example.MyDriver |
| -Dcayenne.jdbc.username=foo |
| -Dcayenne.jdbc.password=bar |
| |
| |
| UPGRADING TO 3.0B1 |
| |
| * Per CAY-1281 pre-persist callback was renamed to post-add (while pre-persist now has a different meaning). |
| To upgrade your project, open it in the Modeler and agree to perform an automated upgrade. |
| |
| UPGRADING TO 3.0M6 |
| |
| * Per CAY-1154, org.apache.cayenne.access.reveng package was renamed to org.apache.cayenne.map.naming. So, if you |
| use your own naming strategies, you should update as well. |
| |
| * Per CAY-1161, custom columns feature in SelectQuery was deprecated. Consider switching to EJBQL as an alternative. |
| Custom columns support will likely go away completely after 3.0M6. |
| |
| * Per CAY-1175, 'columnNameCapitalization' property of SQLTemplate now takes an enum, not a String. |
| Calling code should be fixed. |
| |
| UPGRADING TO 3.0M5 |
| |
| * Per CAY-1127, query "name" property is no longer used as an internal cache key. This change should be transparent |
| to most users, as Cayenne generates a correct cache key internally when needed, however if a user code explicitly |
| depended on the value of the cache key, it should be updated to use something like this: |
| |
| String cacheKey = query.getQueryMetadata(entityResolver).getCacheKey(); |
| |
| UPGRADING TO 3.0M4 |
| |
| * Per CAY-1049 API of the internal classes that participate in SelectQuery translation has changed in a way that |
| is not backwards compatible. This should not affect regular users, however if you implemented a custom DbAdapter, |
| check for classes that directly or indirectly inherit from QueryAssembler and QueryAssemblerHelper and fix them |
| if needed. |
| |
| UPGRADING TO 3.0M3 |
| |
| * Java 5 is now required as a minimum for Cayenne Modeler and the Cayenne libraries. |
| |
| * After the move to Java 5, generics have been implemented in many of the Cayenne APIs. If you don't use generics |
| in your project this should not affect you, but if you do you will need to review any new compiler errors or warnings. |
| The effect of generics is at compile time only, so their introduction will not change the runtime behaviour of |
| your application once compiled. |
| |
| UPGRADING TO 3.0M2 |
| |
| * Lifecycle Callbacks require no setup: |
| Per CAY-843, lifecycle callback functionality is now built into DataContext and DataDomain, |
| so all the custom code to set them up is no longer needed. Also as a result of this change |
| 'org.apache.cayenne.intercept' package is removed from Cayenne. |
| Further information can be found here: http://cayenne.apache.org/doc/lifecycle-callbacks.html |
| |
| UPGRADING TO 3.0M1 |
| |
| * Jar files: |
| - all jar files now include version numbers in their names. |
| - "cayenne-nodeps.jar" is renamed to "cayenne-server-x.x.x.jar" |
| - "fat" cayenne.jar file that included dependencies is no longer distributed. |
| All dependencies that it contained are included as separate jars under |
| "cayenne-x.x.x/lib/third-party/". The new "cayenne-server-x.x.x.jar" plus |
| dependencies should be used in place of cayenne.jar. |
| - A new "cayenne-agent-x.x.x.jar" is included. It is used for class enhancement |
| with POJO's and JPA. "Classic" Cayenne users can ignore this file. |
| |
| * Ant class generator is using what was called "version 1.2" by default. This means that if you were |
| using custom Velocity templates in 1.1 mode, you should either change the templates or specify 'version="1.1"' |
| in the buildfile explicitly. |
| |
| * Cross-platform Modeler Startup is now done without a batch file or a shell script. |
| A "fat" CayenneModeler.jar is included in the "cayenne-x.x.x/bin" directory |
| and can be run either by double-clicking the jar (on platforms that support that) |
| or by running "java -jar CayenneModeler.jar". |
| |
| * Note that FireBird adapter is no longer distributed with Cayenne. The one we had was half-working |
| and we could not support it anymore. |
| |
| * DataContextTransactionEventListener, DataObjectTransactionEventListener, DataContextEvent all were deprecated |
| favor of callbacks. NOTE THAT THIS API WILL BE REMOVED IN THE FOLLOWING 3.0 MILESTONES. |
| |
| * Long PK: Cayenne now supports "long" primary key generation (previously it only supported "int"). You may |
| have to change the existing PK lookup tables on some databases to take advantage of that (this is optional, |
| and is needed if you expect your PK to exceed maximum value of an "int" allowed in your database). E.g. on |
| MySQL you may run the following SQL: |
| |
| ALTER TABLE AUTO_PK_SUPPORT CHANGE COLUMN NEXT_ID NEXT_ID BIGINT NOT NULL; |
| |
| |
| UPGRADING TO 2.0.x |
| |
| Since 2.0, Cayenne is an Apache project, so all "org.objectstyle.*" java packages |
| were renamed to "org.apache.*" analogues. Since 1.2.x and 2.0.x release lines maintain |
| full compatibility with each other, differing only in package names, upgrading to 2.0.x |
| can be a first step in a safe upgrade to the latest version of Cayenne. |
| |
| * Upgrading mapping files: |
| |
| To upgrade the mapping files, open them in the new Modeler. You should see an upgrade |
| dialog. Once you confirm the upgrade |
| |
| * Upgrading the code: |
| |
| Replace "org.objectstyle." with "org.apache." everywhere in imports and do a clean |
| recompile. |
| |
| * Upgrading logging configuration |
| |
| If you are using custom logging configuration file, make sure that all the |
| Cayenne loggers are changed from "org.objectstyle" to "org.apache". |