[#442] Add support for GenQuery2 API.

jargon-core/src/main/java/org/irods/jargon/core/packinstr/Genquery2Input.java

@@ -0,0 +1,92 @@
+package org.irods.jargon.core.packinstr;
+
+import org.irods.jargon.core.exception.JargonException;
+
+/**
+ * Represents a packing instruction for GenQuery2 API operations.
+ */
+public class Genquery2Input extends AbstractIRODSPackingInstruction {
+
+	public static final String PI_TAG = "Genquery2Input_PI";
+
+	public static final int GENQUERY2_API_NBR = 10221;
+
+	private String queryString = "";
+	private String zone = "";
+	private int sqlOnly = 0;
+	private int columnMappings = 0;
+
+	/**
+	 * Creates a packing instruction for querying the catalog.
+	 * 
+	 * @param queryString The GenQuery2 string to execute.
+	 * @param zone        The zone to execute the query against.
+	 * @return {@link Genquery2Input}
+	 */
+	public static Genquery2Input instanceForQuery(final String queryString, final String zone) {
+		Genquery2Input input = new Genquery2Input();
+		input.setApiNumber(GENQUERY2_API_NBR);
+		input.queryString = queryString;
+		input.zone = zone;
+		return input;
+	}
+
+	/**
+	 * Creates a packing instruction for generating SQL from the passed GenQuery2
+	 * string.
+	 * 
+	 * @param queryString The GenQuery2 string to convert to SQL.
+	 * @param zone        The zone to execute the operation against.
+	 * @return {@link Genquery2Input}
+	 */
+	public static Genquery2Input instanceForSqlOnly(final String queryString, final String zone) {
+		Genquery2Input input = new Genquery2Input();
+		input.setApiNumber(GENQUERY2_API_NBR);
+		input.queryString = queryString;
+		input.zone = zone;
+		input.sqlOnly = 1;
+		return input;
+	}
+
+	/**
+	 * Creates a packing instruction for retrieving the GenQuery2 column mappings
+	 * supported by the iRODS Provider.
+	 * 
+	 * @param zone The zone to execute the operation against.
+	 * @return {@link Genquery2Input}
+	 */
+	public static Genquery2Input instanceForColumnMappings(final String zone) {
+		Genquery2Input input = new Genquery2Input();
+		input.setApiNumber(GENQUERY2_API_NBR);
+		input.zone = zone;
+		input.columnMappings = 1;
+		return input;
+	}
+
+	public String getQueryString() {
+		return queryString;
+	}
+
+	public String getZone() {
+		return zone;
+	}
+
+	public int getSqlOnlyValue() {
+		return sqlOnly;
+	}
+
+	public int getColumnMappingsValue() {
+		return columnMappings;
+	}
+
+	@Override
+	public Tag getTagValue() throws JargonException {
+		return new Tag(PI_TAG, new Tag[] {
+			new Tag("query_string", getQueryString()),
+			new Tag("zone", getZone()),
+			new Tag("sql_only", getSqlOnlyValue()),
+			new Tag("column_mappings", getColumnMappingsValue())
+		});
+	}
+
+}

jargon-core/src/main/java/org/irods/jargon/core/pub/IRODSAccessObjectFactory.java

@@ -544,5 +544,15 @@ AuthResponse authenticateIRODSAccountUtilizingCachedConnectionIfPresent(IRODSAcc
 	 * @throws JargonException {@link JargonExecutor}
 	 */
 	ApiPluginExecutor getApiPluginExecutor(final IRODSAccount irodsAccount) throws JargonException;
+
+	/**
+	 * Get an instance of {@link IRODSGenquery2Executor} for querying the catalog
+	 * using GenQuery2.
+	 * 
+	 * @param irodsAccount {@link IRODSAccount}
+	 * @return {@link IRODSGenquery2Executor}
+	 * @throws JargonException {@link JargonException}
+	 */
+	IRODSGenquery2Executor getIRODSGenquery2Executor(final IRODSAccount irodsAccount) throws JargonException;
 
 }

jargon-core/src/main/java/org/irods/jargon/core/pub/IRODSAccessObjectFactoryImpl.java

@@ -675,5 +675,9 @@ public DiscoveredServerPropertiesCache getDiscoveredServerPropertiesCache() {
 	public boolean isUsingDynamicServerPropertiesCache() {
 		return getIrodsSession().isUsingDynamicServerPropertiesCache();
 	}
+
+	public IRODSGenquery2Executor getIRODSGenquery2Executor(final IRODSAccount irodsAccount) throws JargonException {
+		return new IRODSGenquery2ExecutorImpl(irodsSession, irodsAccount);
+	}
 
 }

jargon-core/src/main/java/org/irods/jargon/core/pub/IRODSGenquery2Executor.java

@@ -0,0 +1,85 @@
+package org.irods.jargon.core.pub;
+
+import org.irods.jargon.core.exception.JargonException;
+
+/**
+ * The interface to the GenQuery2 API.
+ */
+public interface IRODSGenquery2Executor extends IRODSAccessObject {
+
+	/**
+	 * Query the catalog using a GenQuery2 string.
+	 * 
+	 * The zone defined in the IRODSAccount will be used.
+	 * 
+	 * This method DOES NOT provide support for pagination.
+	 * 
+	 * @param queryString The GenQuery2 string to execute.
+	 * @return A JSON string containing the results. The structure will be a list of
+	 *         list of strings.
+	 * @throws JargonException If an error occurs.
+	 */
+	String execute(final String queryString) throws JargonException;
+
+	/**
+	 * Query the catalog using a GenQuery2 string.
+	 * 
+	 * This method DOES NOT provide support for pagination.
+	 * 
+	 * @param queryString The GenQuery2 string to execute.
+	 * @param zone        The zone to execute against.
+	 * @return A JSON string containing the results. The structure will be a list of
+	 *         list of strings.
+	 * @throws JargonException If an error occurs.
+	 */
+	String execute(final String queryString, final String zone) throws JargonException;
+
+	/**
+	 * Get the SQL produced by the GenQuery2 API.
+	 * 
+	 * The zone defined in the IRODSAccount will be used. No SQL is executed.
+	 * 
+	 * @param queryString The GenQuery2 string to convert to SQL.
+	 * @return The generated SQL.
+	 * @throws JargonException If an error occurs.
+	 */
+	String getGeneratedSQL(final String queryString) throws JargonException;
+
+	/**
+	 * Get the SQL produced by the GenQuery2 API.
+	 * 
+	 * No SQL is executed.
+	 * 
+	 * @param queryString The GenQuery2 string to convert to SQL.
+	 * @param zone        The zone to execute against.
+	 * @return The generated SQL.
+	 * @throws JargonException If an error occurs.
+	 */
+	String getGeneratedSQL(final String queryString, final String zone) throws JargonException;
+
+	/**
+	 * Get the list of column mappings supported by the GenQuery2 API.
+	 * 
+	 * The zone defined in the IRODSAccount will be used.
+	 * 
+	 * The results will be produced from the iRODS Catalog Provider.
+	 * 
+	 * @return A JSON string containing the mappings between GenQuery2 columns and
+	 *         database columns.
+	 * @throws JargonException If an error occurs.
+	 */
+	String getColumnMappings() throws JargonException;
+
+	/**
+	 * Get the list of column mappings supported by the GenQuery2 API.
+	 * 
+	 * The results will be produced from the iRODS Catalog Provider.
+	 * 
+	 * @param zone The zone to execute against.
+	 * @return A JSON string containing the mappings between GenQuery2 columns and
+	 *         database columns.
+	 * @throws JargonException If an error occurs.
+	 */
+	String getColumnMappings(final String zone) throws JargonException;
+
+}

jargon-core/src/main/java/org/irods/jargon/core/pub/IRODSGenquery2ExecutorImpl.java

@@ -0,0 +1,89 @@
+package org.irods.jargon.core.pub;
+
+import org.irods.jargon.core.connection.IRODSAccount;
+import org.irods.jargon.core.connection.IRODSSession;
+import org.irods.jargon.core.exception.JargonException;
+import org.irods.jargon.core.packinstr.Genquery2Input;
+import org.irods.jargon.core.packinstr.Tag;
+
+public class IRODSGenquery2ExecutorImpl extends IRODSGenericAO implements IRODSGenquery2Executor {
+
+	public IRODSGenquery2ExecutorImpl(IRODSSession irodsSession, IRODSAccount irodsAccount) throws JargonException {
+		super(irodsSession, irodsAccount);
+	}
+
+	@Override
+	public String execute(final String queryString) throws JargonException {
+		return execute(queryString, getIRODSAccount().getZone());
+	}
+
+	@Override
+	public String execute(final String queryString, final String zone) throws JargonException {
+		if (null == queryString || queryString.isEmpty()) {
+			throw new IllegalArgumentException("Query string is null or empty");
+		}
+
+		if (null == zone || zone.isEmpty()) {
+			throw new IllegalArgumentException("Zone string is null or empty");
+		}
+
+		final Genquery2Input input = Genquery2Input.instanceForQuery(queryString, zone);
+		final Tag tag = getIRODSProtocol().irodsFunction(input);
+
+		if (null == tag) {
+			return null;
+		}
+
+		return tag.getTag("myStr").getStringValue();
+	}
+
+	@Override
+	public String getGeneratedSQL(final String queryString) throws JargonException {
+		return getGeneratedSQL(queryString, getIRODSAccount().getZone());
+	}
+
+	@Override
+	public String getGeneratedSQL(final String queryString, final String zone) throws JargonException {
+		if (null == queryString || queryString.isEmpty()) {
+			throw new IllegalArgumentException("Query string is null or empty");
+		}
+
+		if (null == zone || zone.isEmpty()) {
+			throw new IllegalArgumentException("Zone string is null or empty");
+		}
+
+		final Genquery2Input input = Genquery2Input.instanceForSqlOnly(queryString, zone);
+		final Tag tag = getIRODSProtocol().irodsFunction(input);
+
+		if (null == tag) {
+			return null;
+		}
+
+		return tag.getTag("myStr").getStringValue();
+	}
+
+	@Override
+	public String getColumnMappings() throws JargonException {
+		final Genquery2Input input = Genquery2Input.instanceForColumnMappings(getIRODSAccount().getZone());
+		final Tag tag = getIRODSProtocol().irodsFunction(input);
+
+		if (null == tag) {
+			return null;
+		}
+
+		return tag.getTag("myStr").getStringValue();
+	}
+
+	@Override
+	public String getColumnMappings(final String zone) throws JargonException {
+		final Genquery2Input input = Genquery2Input.instanceForColumnMappings(zone);
+		final Tag tag = getIRODSProtocol().irodsFunction(input);
+
+		if (null == tag) {
+			return null;
+		}
+
+		return tag.getTag("myStr").getStringValue();
+	}
+
+}