ServerJoin.java
/*
** Module : ServerJoin.java
** Abstract : Natural join helper implementation for server-side queries
**
** Copyright (c) 2006-2023, Golden Code Development Corporation.
**
** -#- -I- --Date-- -JPRM- ------------------------------------Description------------------------------------
** 001 ECF 20060309 @25004 Created initial version. Natural join helper implementation used by server-side
** (i.e., preselect) query types.
** 002 ECF 20070629 @35301 Minor optimization. Replaced StringBuffer with StringBuilder.
** 003 SVL 20080421 @38074 Updated to meet the AbstractJoin function signatures which may return multiple
** query substitution parameters.
** 004 ECF 20080822 @39562 Added isServerJoin(). Reports whether join occurs at database server or within P2J
** runtime environment.
** 005 SVL 20140210 Use HQLExpression instead of HQL string.
** 006 EVL 20160223 Javadoc fixes to make compatible with Oracle Java 8 for Solaris 10.
** 007 ECF 20200906 New ORM implementation.
** OM 20221103 New class names for FQLPreprocessor, FQLExpression, FQLBundle, and FQLCache.
** 008 OM 20230404 The join navigation key may contain null/unknown values.
*/
/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU Affero General Public License for more details.
**
** You may find a copy of the GNU Affero GPL version 3 at the following
** location: https://www.gnu.org/licenses/agpl-3.0.en.html
**
** Additional terms under GNU Affero GPL version 3 section 7:
**
** Under Section 7 of the GNU Affero GPL version 3, the following additional
** terms apply to the works covered under the License. These additional terms
** are non-permissive additional terms allowed under Section 7 of the GNU
** Affero GPL version 3 and may not be removed by you.
**
** 0. Attribution Requirement.
**
** You must preserve all legal notices or author attributions in the covered
** work or Appropriate Legal Notices displayed by works containing the covered
** work. You may not remove from the covered work any author or developer
** credit already included within the covered work.
**
** 1. No License To Use Trademarks.
**
** This license does not grant any license or rights to use the trademarks
** Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
** of Golden Code Development Corporation. You are not authorized to use the
** name Golden Code, FWD, or the names of any author or contributor, for
** publicity purposes without written authorization.
**
** 2. No Misrepresentation of Affiliation.
**
** You may not represent yourself as Golden Code Development Corporation or FWD.
**
** You may not represent yourself for publicity purposes as associated with
** Golden Code Development Corporation, FWD, or any author or contributor to
** the covered work, without written authorization.
**
** 3. No Misrepresentation of Source or Origin.
**
** You may not represent the covered work as solely your work. All modified
** versions of the covered work must be marked in a reasonable way to make it
** clear that the modified work is not originating from Golden Code Development
** Corporation or FWD. All modified versions must contain the notices of
** attribution required in this license.
*/
package com.goldencode.p2j.persist;
import java.util.List;
import com.goldencode.p2j.persist.orm.*;
/**
* An implementation of a natural join helper used by query types which
* perform the join on the database server. The FQL query string snippet
* created by this class joins the local DMO with the inverse DMO using the
* aliases of each, and does not have a query substitution parameter. For
* instance, given the three table relationship:
* <pre>
* Person [one-to-many] ---> PersonAddress [many-to-one] ---> Address
* </pre>
* and the following multi-table join in Progress
* <pre>
* for each person,
* each person-address of person,
* each address of person-address:
* ...
* </pre>
* the first join (<code>person-address of person</code>) is represented as
* follows:
* <pre>
* personAddress.personRecord = person
* </pre>
* where <code>PersonAddress</code> is the local DMO and Person the foreign
* DMO; and the second join (<code>address of person-address</code>) is
* represented as follows:
* <pre>
* address = personAddress.addressRecord
* </pre>
* where <code>Address</code> is the local DMO and PersonAddress the foreign
* DMO.
*/
final class ServerJoin
extends AbstractJoin
{
/**
* Constructor.
*
* @param local
* Local record buffer (the refering end of the join).
* @param inverse
* Inverse record buffer (the referent end of the join).
*/
ServerJoin(RecordBuffer local, final RecordBuffer inverse)
{
super(local, inverse);
}
/**
* Report whether the join represented by this object takes place at the
* database server, or within runtime code.
*
* @return <code>true</code> if the join happens at the server;
* <code>false</code> if it happens in the runtime.
*/
protected boolean isServerJoin()
{
return true;
}
/**
* Generate the FQL where clause snippets which will be inserted into the overall FQL statement executed by
* the enclosing query. See the class description for additional details on the composition of the clause.
*
* @param local
* Local record buffer (the refering end of the join).
* @param inverse
* Inverse record buffer (the referent end of the join).
* @param info
* Relation descriptor object.
* @param dereference
* {@code true} if the local DMO contains a reference to the foreign record, which must be
* dereferenced in the FQL query; {@code false} if the local DMO <i>is</i> the foreign record,
* referenced by the inverse DMO.
*
* @return FQL where clause snippets used to perform the join. A bi-dimensional array of clauses are used.
* The first dimension is the size of the join (aka the number of fields paired) and the second is
* always two: the first (NULL_FIELD) is used when the joined field is {@code null} and the second
* (NOT_NULL_FIELD) is used when the join field is not unknown.
*/
protected FQLExpression[][] generateFQL(RecordBuffer local,
RecordBuffer inverse,
RelationInfo info,
boolean dereference)
{
String localAlias = local.getDMOAlias();
String inverseAlias = inverse.getDMOAlias();
FQLExpression[][] fqls = new FQLExpression[1][2];
fqls[0][NULL_FIELD] = new FQLExpression(localAlias);
fqls[0][NOT_NULL_FIELD] = new FQLExpression(localAlias);
if (dereference)
{
fqls[0][NULL_FIELD].append(".").append(inverseAlias).append("Record is null");
fqls[0][NOT_NULL_FIELD].append(".").append(inverseAlias).append("Record = ").append(inverseAlias);
}
else
{
fqls[0][NULL_FIELD].append(" is null");
fqls[0][NOT_NULL_FIELD]
.append(" = ").append(inverseAlias).append(".").append(localAlias).append("Record");
}
return fqls;
}
/**
* Determine the type of the query substitution parameters, if any. Since this implementation
* utilizes no query substitution parameter, this method always returns {@code null}.
*
* @param info
* Not used.
* @param dereference
* Not used.
*
* @return {@code null}.
*/
@Override
protected List<FqlType> getParameterTypes(RelationInfo info, boolean dereference)
{
return null;
}
}