src/main/site/content/docs/4.2/upgrade-guide.html

---
#  Licensed to the Apache Software Foundation (ASF) under one
#  or more contributor license agreements.  See the NOTICE file
#  distributed with this work for additional information
#  regarding copyright ownership.  The ASF licenses this file
#  to you under the Apache License, Version 2.0 (the
#  "License"); you may not use this file except in compliance
#  with the License.  You may obtain a copy of the License at
#
#    https://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing,
#  software distributed under the License is distributed on an
#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#  KIND, either express or implied.  See the License for the
#  specific language governing permissions and limitations
#  under the License.

title: "Guide to 4.2 Features"
description: "This guide highlights the new features and changes introduced in Apache Cayenne 4.2"
cayenneVersion: "4.2"
docsMenuTitle: "Upgrade Guide"
weight: 50
---


<div class="sect1"> 
 <h2 id="java-version"><a class="anchor" href="#java-version"></a>1. Java Version</h2> 
 <div class="sectionbody"> 
  <div class="paragraph"> 
   <p>Minimum required JDK version is 8 or newer. Cayenne 4.2 is fully tested with Java 8, 11 and 17.</p> 
  </div> 
 </div> 
</div> 
<div class="sect1"> 
 <h2 id="new-features"><a class="anchor" href="#new-features"></a>2. New Features</h2> 
 <div class="sectionbody"> 
  <div class="sect2"> 
   <h3 id="subqueries"><a class="anchor" href="#subqueries"></a>2.1. Subqueries</h3> 
   <div class="paragraph"> 
    <p>Expressions are now support subqueries.</p> 
   </div> 
   <div class="listingblock"> 
    <div class="content"> 
     <pre class="highlight"><code class="language-java java" data-lang="java">ColumnSelect&lt;Long&gt; subQuery = ObjectSelect
        .columnQuery(Artist.class, Artist.ARTIST_ID_PK_PROPERTY)
        .where(...);
List&lt;Artist&gt; artists = ObjectSelect.query(Artist.class)
        .where(Artist.ARTIST_ID_PK_PROPERTY.in(subQuery))
        .select(context);</code></pre> 
    </div> 
   </div> 
  </div> 
  <div class="sect2"> 
   <h3 id="new-property-api"><a class="anchor" href="#new-property-api"></a>2.2. New Property API</h3> 
   <div class="paragraph"> 
    <p>Property API are greatly revised. This API allows to use type aware expression factories aka Properties. These properties are normally generated as static constants in model classes, but they can also be created manually by <code>PropertyFactory</code> if needed. New API provides designated properties for different datatypes and relationships, including special variant that represents primary keys.</p> 
   </div> 
   <div class="paragraph"> 
    <p>Usage example in <code>ObjectSelect</code> query:</p> 
   </div> 
   <div class="listingblock"> 
    <div class="content"> 
     <pre class="highlight"><code class="language-java java" data-lang="java">Painting painting = //...
Artist artist = ObjectSelect.query(Artist.class)
        .where(Artist.PAINTING_ARRAY.contains(painting))
        .and(Artist.DATE_OF_BIRTH.year().gt(1950))
        .and(Artist.ARTIST_NAME.lower().like("pablo%"))
        .selectOne(context);</code></pre> 
    </div> 
   </div> 
   <div class="paragraph"> 
    <p>See <a href="https://cayenne.apache.org/docs/4.2/api/org/apache/cayenne/exp/property/package-summary.html">JavaDoc</a> for details.</p> 
   </div> 
  </div> 
  <div class="sect2"> 
   <h3 id="new-types-support"><a class="anchor" href="#new-types-support"></a>2.3. New types support</h3> 
   <div class="paragraph"> 
    <p>Cayenne 4.2 brings support for the Json and Geo types that are common now in RDBMS, see <a href="https://github.com/apache/cayenne-examples/tree/master/cayenne-jdbc-type-other">this demo</a> for the usage example. Additionally, Cayenne now supports <code>java.time.Duration</code> and <code>java.time.Period</code> out of the box.</p> 
   </div> 
  </div> 
 </div> 
</div> 
<div class="sect1"> 
 <h2 id="deprecations-and-api-incompatibilities"><a class="anchor" href="#deprecations-and-api-incompatibilities"></a>3. Deprecations and API incompatibilities</h2> 
 <div class="sectionbody"> 
  <div class="paragraph"> 
   <p>For the full list of deprecations refer to <code>UPGRADE.txt</code>. Here’s the most important changes.</p> 
  </div> 
  <div class="sect2"> 
   <h3 id="selectquery"><a class="anchor" href="#selectquery"></a>3.1. SelectQuery</h3> 
   <div class="paragraph"> 
    <p><code>SelectQuery</code> is deprecated in favour of <code>ObjectSelect</code>. It’s still fully functional and could be used, but it will be removed in a future.</p> 
   </div> 
  </div> 
  <div class="sect2"> 
   <h3 id="obsolete-modules"><a class="anchor" href="#obsolete-modules"></a>3.2. Obsolete modules</h3> 
   <div class="paragraph"> 
    <p>There are several modules that are deprecated in Cayenne 4.2 and will be removed in a later version:</p> 
   </div> 
   <div class="ulist"> 
    <ul> 
     <li> <p>Cayenne ROP</p> </li> 
     <li> <p>Cayenne Web</p> </li> 
     <li> <p>Event bridges: XMPP, JMS and JGroups</p> </li> 
    </ul> 
   </div> 
   <div class="paragraph"> 
    <p>These modules could be still safely used in 4.2.</p> 
   </div> 
  </div> 
  <div class="sect2"> 
   <h3 id="objectid"><a class="anchor" href="#objectid"></a>3.3. ObjectId</h3> 
   <div class="paragraph"> 
    <p>ObjectId can’t be instantiated directly, <code>ObjectId.of(..)</code> factory methods should be used. E.g. <code>ObjectId.of("Artist", 1)</code> instead of <code>new ObjectId("Artist", 1)</code>.</p> 
   </div> 
  </div> 
 </div> 
</div>