-
Notifications
You must be signed in to change notification settings - Fork 132
/
UPGRADE.txt
333 lines (242 loc) · 17.6 KB
/
UPGRADE.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
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.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
where 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".