001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: LogQuery.java,v 1.4 2008/06/25 05:43:35 qcheng Exp $
026 *
027 */
028
029/*
030 * Portions Copyrighted [2011] [ForgeRock AS]
031 */
032package com.sun.identity.log;
033
034import java.util.ArrayList;
035
036/**
037 * LogQuery defines the query format that the reader api supports.
038 * This class contains a list of individual query elements
039 * and also stores information about whether all the query to
040 * be satisfied or any one to be satisfied. It also allows
041 * caller to set required number of most recent records and
042 * to specify the <code>sortby</code> field name (optional).
043 * @supported.all.api
044 */
045
046public class LogQuery {
047    /**
048     * matching condition, values of globalOperand.
049     * All the queries to be applied successfully
050     */
051    static public final int MATCH_ALL_CONDITIONS = 1;
052
053    /* Any one of the query must be true */
054    static public final int MATCH_ANY_CONDITION  = 2;
055    
056    /**
057     * when maximum records asked
058     * Most recent maximum number of records to be collected.
059     * Here maximum number will be as stored in the configuration.
060     */
061    static public final int MOST_RECENT_MAX_RECORDS = -1;
062
063    /**
064     * All the records that matches query criteria (if any)
065     * will be retrieved. Maximum number of records as configured
066     * will be ignored.
067     */
068    static public final int ALL_RECORDS = -2;
069    
070    // private attributes
071    private int maxRecord;
072    private int globalOperand;
073    private ArrayList queries;  /* list of QueryElement object */
074    private ArrayList columns;  /* columns requested */
075    private String sortBy;
076    
077    /**
078     * Default constructor
079     * It creates the new object and assigns space to them.
080     * It sets default values when applicable.
081     **/
082    public LogQuery() {
083        this.maxRecord = LogQuery.MOST_RECENT_MAX_RECORDS;
084        this.globalOperand = LogQuery.MATCH_ANY_CONDITION;
085        this.queries = null;
086        this.columns = null;
087        this.sortBy = null;
088    }
089    
090    /**
091     * Customized constructor to set only <code>maxrecord</code>.
092     *
093     * @param max_record is maximum number of most recent records to be
094     *        returned.
095     */
096    public LogQuery(int max_record) {
097        this.maxRecord = max_record;
098        this.globalOperand = LogQuery.MATCH_ANY_CONDITION;
099        this.queries = null;
100        this.columns = null;
101        this.sortBy = null;
102    }
103    
104    /**
105     * Customized constructor.
106     *
107     * @param max_Record the maximum number of most recent records
108     *        to be returned
109     * @param matchCriteria whether all queries or any one to match.
110     * @param sortingBy <code>fieldname</code> on which records to be sorted.
111     * @throws IllegalArgumentException if any of the
112     *         <code>max_Record/matchCriteria</code> is not valid.
113     */
114    public LogQuery(int max_Record, int matchCriteria, String sortingBy)
115    throws IllegalArgumentException {
116        if (max_Record < LogQuery.ALL_RECORDS) {
117            throw new IllegalArgumentException(
118            "max_Record should be greater than LogQuery.ALL_RECORDS");
119        } else {
120            this.maxRecord = max_Record;
121        }
122        if ((matchCriteria > LogQuery.MATCH_ANY_CONDITION) ||
123            (matchCriteria < LogQuery.MATCH_ALL_CONDITIONS))
124        {
125            throw new IllegalArgumentException(
126                "matchCriteria should be LogQuery.MATCH_ANY_CONDITION or " +
127                "LogQuery.MATCH_ALL_CONDITIONS");
128        } else {
129            this.globalOperand = matchCriteria;
130        }
131        if (sortingBy != null) {
132            this.sortBy = sortingBy;
133        }
134        this.queries = null;
135        this.columns = null;
136    }
137    
138    /**
139     * Sets the <code>globalOperand</code> field to either any query criteria
140     * match or to match all the criteria.
141     *
142     * @param no the value to set to <code>globalOperand</code>
143     * @throws IllegalArgumentException when parameter is passed as
144     *         neither all nor any match.
145     */
146    public void setGlobalOperand (int no)
147        throws IllegalArgumentException
148    {
149        if (no > LogQuery.MATCH_ANY_CONDITION) {
150            IllegalArgumentException ie = new IllegalArgumentException(
151                "parameter should be LogQuery.MATCH_ANY_CONDITION or " +
152                "LogQuery.MATCH_ALL_CONDITIONS");
153            throw (ie);
154        } else if (no < LogQuery.MATCH_ALL_CONDITIONS) {
155            IllegalArgumentException ie = new IllegalArgumentException(
156            "parameter should be LogQuery.MATCH_ANY_CONDITION or " +
157            "LogQuery.MATCH_ALL_CONDITIONS");
158            throw (ie);
159        }
160        this.globalOperand = no;
161    }
162    
163    /*
164     * Sets maxRecord i.e. maximum number of records to return to the
165     * user specified value.
166     * It checks whether it exceeds the configured maximum value or not.
167     *
168     * @param value the maximum number of records to return.
169     */
170    public void setMaxRecord(int value) {
171        if (value < LogQuery.ALL_RECORDS) {
172            return;
173        }
174        this.maxRecord = value;
175    }
176    
177    /**
178     * Adds a query element to the list present in <code>LogQuery</code>.
179     *
180     * @param qryElement the query to be added into the list
181     */
182    public void addQuery(QueryElement qryElement) {
183        if (qryElement == null) {
184            return;
185        }
186        if (this.queries == null) {
187            this.queries = new ArrayList();
188        }
189        this.queries.add(qryElement);
190    }
191    
192    /**Returns the full list of query
193     *
194     * @return full list of query
195     **/
196    public ArrayList getQueries() {
197        return (this.queries);
198    }
199    
200    /*
201     * Returns max number of records asked for.
202     *
203     * @return max number of records asked for.
204     */
205    public int getNumRecordsWanted() {
206        return (this.maxRecord);
207    }
208    
209    /**
210     * Returns the value of global operand set in the query.
211     *
212     * @return the value of global operand set in the query.
213     */
214    public int getGlobalOperand() {
215        return (this.globalOperand);
216    }
217    
218    /**
219     * Set the field name on which records to be sorted.
220     *
221     * @param fieldName field name on which records to be sorted.
222     */
223    public void setSortingField(String fieldName) {
224        if (fieldName == null) {
225            return;
226        }
227        this.sortBy = fieldName;
228    }
229    
230    /**
231     * Returns the field name on which records to be sorted.
232     *
233     * @return the field name on which records to be sorted.
234     */
235    public String getSortingField() {
236        return (this.sortBy);
237    }
238
239    /**
240     * Set the columns to be selected.  This applies to flatfile
241     * logging also; means "fields", rather than "columns" then.
242     *
243     * @param columns to request.
244     */
245    public void setColumns(ArrayList columns) {
246        if ((columns == null) || (columns.isEmpty())) {
247            return;
248        }
249        this.columns = columns;
250    }
251    
252    /**
253     * Returns the table column names selected.  This applies to flatfile
254     * logging also; means "fields", rather than "columns" then.
255     *
256     * @return the ArrayList of columns specified.
257     */
258    public ArrayList getColumns() {
259        return (this.columns);
260    }
261
262
263}