Results.java
/*
** Module : Results.java
** Abstract : Abstraction layer interface for query results
**
** Copyright (c) 2006-2024, Golden Code Development Corporation.
**
** -#- -I- --Date-- --JPRM-- ---------------------------Description------------------------------
** 001 ECF 20060214 @24711 Created initial version. Defines an API which abstracts the results
** of a joinable query.
** 002 ECF 20060725 @28190 Added cleanup() method.
** 003 ECF 20070711 @34444 Added sessionClosing() method. This is needed in addition to
** cleanup() because it may be necessary to behave differently at
** session closing than at the end of the Results object's life.
** 004 ECF 20190427 Fixed results caching.
** 005 SVL 20191002 Added addRow.
** 006 ECF 20200906 New ORM implementation.
** 007 AL2 20230315 Added isAutoFetch.
** 008 AD 20231110 Added get() method with forceOnlyId parameter, with default implementation.
** AD 20231113 Added warning log in default implementation of get(boolean).
** AD 20231116 Made logger from default get() a static field.
** AD 20231124 Added condition when logging use of default implementation of get(boolean).
** 009 AL2 20240906 Made get call get(forceIdOnly) with false argument by default.
*/
/*
** 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 com.goldencode.p2j.util.logging.CentralLogger;
/**
* An abstraction layer between a joinable query implementation and its results. This interface
* defines methods for manipulating a results set using a scrollable cursor paradigm. Each row
* is a virtual composite of one or more records, each represented by its primary key ID or by a
* reference to the DMO itself.
*/
interface Results
{
/** Logger */
static final CentralLogger LOG = CentralLogger.get(Results.class.getName());
/**
* Move cursor to the first results row.
*
* @return {@code true} if there are any results.
*/
public boolean first();
/**
* Move cursor to the last results row.
*
* @return {@code true} if there are any results.
*/
public boolean last();
/**
* Move cursor to the next results row.
*
* @return {@code true} if there is a result under the cursor after the move.
*/
public boolean next();
/**
* Move cursor to the previous results row.
*
* @return {@code true} if there is a result under the cursor after the move.
*/
public boolean previous();
/**
* Is the cursor on the first row in the results set?
*
* @return {@code true} if the cursor is on the first row.
*/
public boolean isFirst();
/**
* Is the cursor on the last row in the results set?
*
* @return {@code true} if the cursor is on the first row.
*/
public boolean isLast();
/**
* Is the result delegate responsible for fetching? This is usually true when using
* query delegates which handle the fetching process already.
*
* @return {@code true} for complex results which also do the fetching.
*/
default public boolean isAutoFetch()
{
return false;
}
/**
* Get the array of objects at the current result row.
*
* @return Object array or {@code null}.
*/
default public Object[] get()
{
return get(false);
}
/**
* Returns the row at the current position. It can be either only an array of PK or
* an array of DMOs.
*
* @param forceOnlyId
* Indicates whether it's only the primary keys that must be returned,
* or original data found is returned (either PK or DMO).
*
* @return Object array or {@code null}.
*/
public Object[] get(boolean forceOnlyId);
/**
* Get the object at the current result row, at the specified column.
*
* @param column
* Zero-based index column of the desired object.
*
* @return Object at {@code column} or {@code null}.
*/
public Object get(int column);
/**
* Get the primary key ID at the current result row, at the specified column.
*
* @param column
* Zero-based index column of the desired ID.
*
* @return ID of the record or {@code null}.
*/
public Long getID(int column);
/**
* Get the row number currently under the cursor.
*
* @return Zero-based index of the current row, or {@code -1} if the cursor is not currently
* on a result.
*/
public int getRowNumber();
/**
* Set the row number currently under the cursor.
*
* @param row
* Zero-based index of the row to be set as the current row.
*
* @return {@code true} if there is a row at the specified row number, else {@code false}.
*/
public boolean setRowNumber(int row);
/**
* Scroll the cursor ahead by the specified number of rows. If the number is negative, the
* cursor is moved backward. This may put the cursor off the end (either end) of the query's
* results.
*
* @param rows
* Number of rows to jump ahead or back.
*
* @return {@code true} if there is a row at the new location, else {@code false}.
*/
public boolean scroll(int rows);
/**
* Reset the cursor to its natural starting position, before the first result row.
*/
public void reset();
/**
* Invoked when the current Hibernate session is about to close. Gives the implementation an
* opportunity to perform appropriate processing in response to this event.
*/
public void sessionClosing();
/**
* Clean up and release any resources which this object is holding, such as open result sets.
*/
public void cleanup();
/**
* Indicate whether the full result set is cached in this object.
*
* @return {@code true} if all results are contained this object; {@code false} if not or
* if unknown (such as for a scrolling or cursored result set. Default return value
* is {@code false}.
*/
public default boolean isResultSetCached()
{
return false;
}
/**
* Returns the number of rows which have been loaded by this object.
*
* @return This default implementation returns 0.
*/
public default int getNumberOfLoadedRows()
{
return 0;
}
/**
* Delete the current row. This is an optional operation and this default implementation does
* nothing.
*
* @return {@code true} if the row was deleted. {@code false} if there is no row at
* the current position. This default implementation returns {@code false}.
*/
public default boolean deleteRow()
{
return false;
}
/**
* Add a new row.
*
* @param row
* Row data.
* @param beforeRow
* <code>true</code> if the current position is before the row. <code>false</code> if
* the current position is on the row.
*/
public default void addRow(Object[] row, boolean beforeRow)
{
throw new IllegalStateException("Cannot add a row for this type of results");
}
}