• Home
• com.blazebit
• blaze-query-core-api
• 1.0.6
• source code
• QuerySession.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.blazebit.query.QuerySession Maven / Gradle / Ivy

/*
 * SPDX-License-Identifier: Apache-2.0
 * Copyright Blazebit
 */
package com.blazebit.query;

import com.blazebit.query.metamodel.SchemaObjectType;
import com.blazebit.query.spi.DataFetcherException;

import java.lang.reflect.Type;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * A session within which queries can be executed against schema object data.
 * {@linkplain QuerySession} stores schema object data against which queries run, and if necessary,
 * fetches data by invoking the {@link com.blazebit.query.spi.DataFetcher} registered for a schema object.
 * When the application has finished using the {@linkplain QuerySession}, the application should close the {@linkplain QuerySession}.
 * Once a {@linkplain QuerySession} has been closed, all its {@link Query} objects become unusable.
 * The object is not thread-safe.
 *
 * @author Christian Beikov
 * @since 1.0.0
 */
public interface QuerySession extends AutoCloseable {

	/**
	 * Returns the {@link QueryContext} that created this {@linkplain QuerySession}.
	 *
	 * @return the {@link QueryContext} that created this {@linkplain QuerySession}
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	QueryContext getContext();

	/**
	 * Creates an executable query associated to this {@linkplain QuerySession}.
	 *
	 * @param queryString A Blaze-Query query string
	 * @return a new query instance
	 * @throws IllegalArgumentException If the query string is invalid
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	default TypedQuery createQuery(String queryString) {
		return createQuery( queryString, Object[].class );
	}

	/**
	 * Creates an executable query associated to this {@linkplain QuerySession}.
	 *
	 * @param queryString A Blaze-Query query string
	 * @param properties The properties for the query, which should override {@linkplain QuerySession} properties
	 * @return a new query instance
	 * @throws IllegalArgumentException If the query string is invalid
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	default TypedQuery createQuery(String queryString, Map properties) {
		return createQuery( queryString, Object[].class, properties );
	}

	/**
	 * Creates an executable query associated to this {@linkplain QuerySession}.
	 *
	 * @param queryString A Blaze-Query query string
	 * @param resultClass The result class
	 * @param  The result type
	 * @return a new query instance
	 * @throws IllegalArgumentException If the query string is invalid
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	default  TypedQuery createQuery(String queryString, Class resultClass) {
		return createQuery( queryString, resultClass, Collections.emptyMap() );
	}

	/**
	 * Creates an executable query associated to this {@linkplain QuerySession}.
	 *
	 * @param queryString A Blaze-Query query string
	 * @param resultClass The result class
	 * @param properties The properties for the query, which should override {@linkplain QuerySession} properties
	 * @return a new query instance
	 * @throws IllegalArgumentException If the query string is invalid
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	default  TypedQuery createQuery(String queryString, Class resultClass, Map properties) {
		return createQuery( queryString, new TypeReference<>() {
			@Override
			public Type getType() {
				return resultClass;
			}
		}, properties );
	}

	/**
	 * Creates an executable query associated to this {@linkplain QuerySession}.
	 *
	 * @param queryString A Blaze-Query query string
	 * @param resultType The result type
	 * @return a new query instance
	 * @throws IllegalArgumentException If the query string is invalid
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	default  TypedQuery createQuery(String queryString, TypeReference resultType) {
		return createQuery( queryString, resultType, Collections.emptyMap() );
	}

	/**
	 * Creates an executable query associated to this {@linkplain QuerySession}.
	 *
	 * @param queryString A Blaze-Query query string
	 * @param resultType The result type
	 * @param properties The properties for the query, which should override {@linkplain QuerySession} properties
	 * @param  The result type
	 * @return a new query instance
	 * @throws IllegalArgumentException If the query string is invalid
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	 TypedQuery createQuery(String queryString, TypeReference resultType, Map properties);

	/**
	 * Returns the schema object data for the given schema object type stored in this {@linkplain QuerySession},
	 * or {@code null} if there is none.
	 *
	 * @param schemaObjectType The schema object type
	 * @param  The schema object type
	 * @return the schema object data, or {@code null}
	 * @throws IllegalArgumentException If the schema object type is not known
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	 List get(Class schemaObjectType);

	/**
	 * Returns the schema object data for the given schema object type stored in this {@linkplain QuerySession},
	 * fetching and storing the data by calling the underlying {@link com.blazebit.query.spi.DataFetcher} if necessary.
	 *
	 * @param schemaObjectType The schema object type
	 * @param  The schema object type
	 * @return the schema object data
	 * @throws IllegalArgumentException If the schema object type is not known
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 * @throws DataFetcherException when an exception occurs during data fetching
	 */
	 List getOrFetch(Class schemaObjectType);

	/**
	 * Stores the given schema objects for the given schema object type in this {@linkplain QuerySession}
	 * and returns the previously stored schema object data stored, or {@code null} if there was none.
	 *
	 * @param schemaObjectType The schema object type
	 * @param schemaObjects The new schema object data to store
	 * @param  The schema object type
	 * @return the previous schema object data, or {@code null}
	 * @throws IllegalArgumentException If the schema object type is not known
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	 List put(Class schemaObjectType, List schemaObjects);

	/**
	 * Removes the schema objects for the given schema object type from this {@linkplain QuerySession}
	 * and returns the previously stored schema object data stored, or {@code null} if there was none.
	 *
	 * @param schemaObjectType The schema object type
	 * @param  The schema object type
	 * @return the previous schema object data, or {@code null}
	 * @throws IllegalArgumentException If the schema object type is not known
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	 List remove(Class schemaObjectType);

	/**
	 * Refreshes the schema object data for the given schema object type by fetching data again through
	 * the underlying {@link com.blazebit.query.spi.DataFetcher}.
	 *
	 * @param schemaObjectType The schema object type
	 * @param  The schema object type
	 * @return the refreshed schema object data
	 * @throws IllegalArgumentException If the schema object type is not known
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 * @throws DataFetcherException when an exception occurs during data fetching
	 */
	default  List refresh(Class schemaObjectType) {
		remove( schemaObjectType );
		return getOrFetch( schemaObjectType );
	}

	/**
	 * Returns the schema object types for which data is stored in this {@linkplain QuerySession}.
	 *
	 * @return the schema object types for which data is stored in this {@linkplain QuerySession}
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	Set> getFetchedSchemaObjectTypes();

	/**
	 * Clears the schema object data fetched by {@link com.blazebit.query.spi.DataFetcher} instances.
	 *
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	void clear();

	/**
	 * Set a {@link QuerySession} property or hint.
	 * If a vendor-specific property or hint is not recognized, it is silently ignored.
	 *
	 * @param propertyName name of property or hint
	 * @param value value for property or hint
	 * @throws IllegalArgumentException if the second argument is not valid for the implementation
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	void setProperty(String propertyName, Object value);

	/**
	 * Returns the properties and hints and associated values that are in effect
	 * for the {@linkplain QuerySession}. Changing the contents of the map does
	 * not change the configuration in effect.
	 *
	 * @return map of properties and hints in effect for the {@linkplain QuerySession}
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	Map getProperties();

	/**
	 * Return an object of the specified type to allow access to the provider-specific API.
	 * If the implementation does not support the specified class, the {@link IllegalArgumentException} is thrown.
	 *
	 * @param cls the class of the object to be returned
	 * @param  The return type
	 * @return The unwrapped object
	 * @throws IllegalArgumentException if the type is not supported
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	 T unwrap(Class cls);

	/**
	 * Determine whether the entity manager is open.
	 *
	 * @return true until the entity manager has been closed
	 */
	public boolean isOpen();

	/**
	 * Closes the {@linkplain QuerySession} to free up resources.
	 *
	 * @throws IllegalStateException if the {@linkplain QuerySession} is closed
	 */
	@Override
	void close();
}