Skip to content

Commit

Permalink
docs: EXPOSED-600 Add links to API docs for functions and classes (#2339
Browse files Browse the repository at this point in the history 
)

* chore: Add API links and improve formatting of the DSL topics

* fix: Formatting of functions and class names in the DAO topics

* chore: Add API links and format names in the Schema topics

* chore: Add API links and format function names in the Databases sub-topics

* fix: Formatting of ID
  • Loading branch information
@vnikolova
vnikolova authored Dec 19, 2024
1 parent d82ca33 commit 8db5269
Show file tree
Hide file tree
Showing 14 changed files with 1,190 additions and 674 deletions.
241 changes: 176 additions & 65 deletions documentation-website/Writerside/topics/DAO-CRUD-Operations.topic
View file

Large diffs are not rendered by default.

56 changes: 32 additions & 24 deletions documentation-website/Writerside/topics/DAO-Entity-definition.topic
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@
database records just like regular Kotlin objects, taking full advantage of Kotlin's language features.
</p>
<p>
When using the DAO approach, <code>IdTable</code> needs to be associated with an <code>Entity</code>,
because every database record
in this table needs to be mapped to an <code>Entity</code> instance, identified by its primary key.
When you use the Data Access Object (DAO) approach, the <code>IdTable</code> needs to be associated with an
<code>Entity</code>. This is because every database record in this table needs to be mapped to an
<code>Entity</code> instance, identified by its primary key.
</p>
<chapter id="defining-entity-class" title="Defining an Entity class">
<chapter id="defining-entity-class" title="Defining an Entity">
<p>
You define an entity instance by creating a class.
In the following example, <code>StarWarsFilmEntity</code> is the entity class linked to the table
Expand All @@ -34,7 +34,7 @@
The entity type determines how the <code>Entity</code> class interacts with the table’s primary key.
Since <code>StarWarsFilmsTable</code> is an <code>IntIdTable</code>, the <code>StarWarsFilmsEntity</code>
class extends from <a href="%BASE_API_URL%/exposed-dao/org.jetbrains.exposed.dao/-int-entity/index.html"><code>IntEntity</code></a>,
which indicates that the <code>id</code> and primary key of <code>StarWarsFilmsTable</code> is of type
which indicates that the ID and primary key of <code>StarWarsFilmsTable</code> is of type
<code>Int</code>.
</p>
<p>
Expand All @@ -48,7 +48,7 @@
</a>
</title>
<p>
Base class for an entity instance identified by an id comprised of a wrapped <code>Int</code>
Base class for an entity instance identified by an ID comprised of a wrapped <code>Int</code>
value.
</p>
</def>
Expand All @@ -59,7 +59,7 @@
</a>
</title>
<p>
Base class for an entity instance identified by an id comprised of a wrapped <code>Long</code>
Base class for an entity instance identified by an ID comprised of a wrapped <code>Long</code>
value.
</p>
</def>
Expand All @@ -70,7 +70,7 @@
</a>
</title>
<p>
Base class for an entity instance identified by an id comprised of a wrapped <code>UInt</code>
Base class for an entity instance identified by an ID comprised of a wrapped <code>UInt</code>
value.
</p>
</def>
Expand All @@ -81,7 +81,7 @@
</a>
</title>
<p>
Base class for an entity instance identified by an id comprised of a wrapped <code>ULong</code>
Base class for an entity instance identified by an ID comprised of a wrapped <code>ULong</code>
value.
</p>
</def>
Expand All @@ -92,7 +92,7 @@
</a>
</title>
<p>
Base class for an entity instance identified by an id comprised of a wrapped <code>UUID</code>
Base class for an entity instance identified by an ID comprised of a wrapped <code>UUID</code>
value.
</p>
</def>
Expand All @@ -103,12 +103,12 @@
</a>
</title>
<p>
Base class for an entity instance identified by an id comprised of multiple wrapped values.
Base class for an entity instance identified by an ID comprised of multiple wrapped values.
</p>
</def>
</deflist>
</chapter>
<chapter id="EntityClass" title="EntityClass">
<chapter title="Entity class" id="EntityClass">
<p>
The <a href="%BASE_API_URL%/exposed-dao/org.jetbrains.exposed.dao/-entity-class/index.html"><code>EntityClass</code></a>
in the <code>companion object</code> block is responsible for managing <code>Entity</code> instances,
Expand All @@ -120,7 +120,7 @@
parameters:</p>
<deflist type="medium">
<def title="table" id="table-param">
The <code>IdTable</code> containing rows mapped to entities managed by this class.
The <code>IdTable</code> containing rows mapped to entities that are managed by this class.
</def>
<def title="entityType" id="entityType-param">
(Optional) The expected type of the <code>Entity</code> class. This can be omitted if it is the
Expand Down Expand Up @@ -151,7 +151,7 @@
</chapter>
<p>
Once the entity class is defined, instances of this class allow you to manipulate individual records
from the corresponding table. This could involve
from the corresponding table. For example, by
<a href="DAO-CRUD-Operations.topic" anchor="create">creating a new record</a>,
<a href="DAO-CRUD-Operations.topic" anchor="read">retrieving a row based on its primary key</a>,
<a href="DAO-CRUD-Operations.topic" anchor="update">updating values</a>, or
Expand Down Expand Up @@ -185,8 +185,8 @@
<li>
The primary function of the entity class in this context is to query data from the associated table,
not to modify it. Therefore, inserts can only be performed using the
DSL <a href="DSL-CRUD-operations.topic" anchor="insert"><code>insert()</code></a> method and updates
can be done either through the DSL <a href="DSL-CRUD-operations.topic" anchor="update"><code>update()</code></a>
DSL <a href="DSL-CRUD-operations.topic" anchor="insert"><code>.insert()</code></a> method and updates
can be done either through the DSL <a href="DSL-CRUD-operations.topic" anchor="update"><code>.update()</code></a>
or the <a href="%BASE_API_URL%/exposed-dao/org.jetbrains.exposed.dao/-immutable-entity-class/force-update-entity.html">
<code>ImmutableEntityClass.forceUpdateEntity()</code></a> methods.
</li>
Expand All @@ -202,41 +202,49 @@
</p>
<code-block lang="kotlin" src="exposed-dao/src/main/kotlin/org/example/entities/UserEntityWithOverride.kt"/>
<p>
In this example, a custom message is printed before the <code>delete()</code> function of the superclass
In this example, a custom message is printed before the <code>.delete()</code> function of the superclass
(<code>IntEntity</code>) completes the deletion.
</p>
</chapter>
<chapter title="Field transformations" id="field-transformations">
<p>
As databases typically store only basic types, such as integers and strings, it's not always convenient to keep
the same simplicity on Data Access Object (DAO) level.
the same simplicity on DAO level.
</p>
<p>
For example, you might need to parse JSON from a <code>VARCHAR</code> column, or retrieve values from a cache
based on data from the database.
In such cases, the preferred approach is to use column transformations.
In such cases, we recommend to use column transformations.
</p>
<chapter title="Example: Defining an Unsigned Integer field" id="defining-unsigned-int-field">
<p>
Suppose that you want to define an unsigned integer field on an entity, but Exposed doesn't have such
Suppose that you want to define an unsigned integer field on an entity, but Exposed doesn't have such a
column type yet. You can achieve this by using the following implementation:
</p>
<code-block lang="kotlin" src="exposed-dao/src/main/kotlin/org/example/entities/EntityWithUInt.kt"/>
<p>
The <code>transform</code> function accept two lambdas that convert values to and from the original column type.
The
<a href="https://jetbrains.github.io/Exposed/api/exposed-dao/org.jetbrains.exposed.dao/-entity-class/transform.html">
<code>.transform()</code>
</a>
function accepts two lambdas that convert values to and from the original column type.
In this case, you make sure to store only <code>UInt</code> instances in the <code>uint</code> field.
</p>
<p>
Although it is still possible to insert or update values with negative integers via DAO, this approach assures
a cleaner business logic.
Although it is still possible to insert or update values with negative integers via DAO, this approach
assures a cleaner business logic.
</p>
</chapter>


<chapter title="Memoized transformations" id="memoized-transformations">
<p>
If your transformation function involves complex operations that impact performance,
you can use <code>memoizedTransform</code> to cache the result of the transformation.
you can use
<a href="https://jetbrains.github.io/Exposed/api/exposed-dao/org.jetbrains.exposed.dao/-entity-class/memoized-transform.html">
<code>.memoizedTransform()</code>
</a>
to cache the result of the transformation.
</p>

<code-block lang="kotlin" src="exposed-dao/src/main/kotlin/org/example/entities/EntityWithBase64.kt"/>
Expand Down
35 changes: 21 additions & 14 deletions documentation-website/Writerside/topics/DAO-Table-Types.topic
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,14 @@
title="Table types" id="DAO-Table-Types" help-id="DAO-Table-types">

<include from="DSL-Table-Types.topic" element-id="dsl-core-table-class"/>
<chapter id="defining-tables">
<title>Auto-incrementing <code>id</code> column tables</title>
<chapter title="Auto-incrementing ID column tables" id="defining-tables">
<snippet id="dao-table-types">
<p>
Apart from the core <code>Table</code> class, Exposed provides the base
<code>IdTable</code> class and its subclasses through the DAO API.
<a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-id-table/index.html">
<code>IdTable</code>
</a>
class and its subclasses through the DAO API.
</p>
<p>
The <code>IdTable</code> class extends <code>Table</code> and is
Expand All @@ -30,22 +32,22 @@
<deflist type="medium">
<def id="IntIdTable">
<title><a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-int-id-table/index.html"><code>IntIdTable</code></a></title>
<code>Int</code> id column</def>
<code>Int</code> ID column</def>
<def id="LongIdTable">
<title><a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-long-id-table/index.html"><code>LongIdTable</code></a></title>
<code>Long</code> id column
<code>Long</code> ID column
</def>
<def id="UIntIdTable">
<title><a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-u-int-id-table/index.html"><code>UIntIdTable</code></a></title>
<code>UInt</code> id column
<code>UInt</code> ID column
</def>
<def id="ULongIdTable">
<title><a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-u-long-id-table/index.html"><code>ULongIdTable</code></a></title>
<code>ULong</code> id column
<code>ULong</code> ID column
</def>
<def id="UUIDTable">
<title><a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-u-u-i-d-table/index.html"><code>UUIDTable</code></a></title>
<code>UUID</code> id column
<code>UUID</code> ID column
</def>
</deflist>
<p>The following example represents a table with custom columns <code>sequel_id</code>, <code>name</code>,
Expand All @@ -70,12 +72,17 @@
</p>
</chapter>

<chapter title="Composite id table" id="composite-id-table">
<chapter title="Composite ID table" id="composite-id-table">
<p>
To define multiple columns as part of the primary key and id, use
<a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-composite-id-table/index.html"><code>CompositeIdTable</code></a>
and mark each composite column using <code>entityId()</code>.
Each component column will be available for CRUD operations either individually (as for any standard column)
To define multiple columns as part of the primary key and ID, use
<a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.dao.id/-composite-id-table/index.html">
<code>CompositeIdTable</code>
</a>
and mark each composite column using
<a href="https://jetbrains.github.io/Exposed/api/exposed-core/org.jetbrains.exposed.sql/-table/entity-id.html">
<code>.entityId()</code>
</a>
.Each component column will be available for CRUD operations either individually (as for any standard column)
or all together as part of the <code>id</code> column:
</p>
<tabs>
Expand All @@ -101,7 +108,7 @@

<chapter title="Custom column type table" id="custom-column-type">
<p>
To define a custom column type as the primary key and id, use a typed <code>IdTable</code> directly and
To define a custom column type as the primary key and ID, use a typed <code>IdTable</code> directly and
override the <code>id</code> column, as shown in the following example:
</p>
<tabs>
Expand Down
Loading

0 comments on commit 8db5269

Please sign in to comment.