001    /*
002     *   Licensed to the Apache Software Foundation (ASF) under one
003     *   or more contributor license agreements.  See the NOTICE file
004     *   distributed with this work for additional information
005     *   regarding copyright ownership.  The ASF licenses this file
006     *   to you under the Apache License, Version 2.0 (the
007     *   "License"); you may not use this file except in compliance
008     *   with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     *   Unless required by applicable law or agreed to in writing,
013     *   software distributed under the License is distributed on an
014     *   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *   KIND, either express or implied.  See the License for the
016     *   specific language governing permissions and limitations
017     *   under the License.
018     *
019     */
020    package org.apache.directory.server.core.changelog;
021    
022    
023    import org.apache.directory.shared.ldap.cursor.Cursor;
024    
025    
026    /**
027     * An optional search interface supported by TaggableChangeLogStores.  This 
028     * interface enables the:
029     * 
030     * <ul>
031     *   <li>lookup of tags by revision</li>
032     *   <li>finding all tags</li>
033     *   <li>finding tags before or after a revision</li>
034     *   <li>finding tags in some revision range</li>
035     * </ul>
036     * 
037     * While investigating these interface methods keep in mind that only one 
038     * tag can exist on a revision.  Unlike subversion which allows multiple 
039     * tags on a revision we only allow at most one: more than one is pointless.
040     * 
041     * Date wise searches for tags are not present within this interface since 
042     * they should be used in conjunction with the ChangeLogSearchEngine which
043     * is by default supported by TaggableSearchableChangeLogStores.  The 
044     * ChangeLogSearchEngine can find revisions based on time descriptors and
045     * returned revisions can be checked for the presence of tags using this
046     * interface.  The whole point to enabling both search engines in a single
047     * interfaces is because if you can search for tags you should be able to 
048     * search for revisions: however the converse may not be the case.
049     * 
050     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
051     * @version $Rev$, $Date$
052     */
053    public interface TagSearchEngine
054    {
055        /**
056         * Gets the tag for a specific snapshot if that snapshot exists. 
057         *
058         * @param revision the revision number to use to check for a snapshot
059         * @return the snapshot at the revision if one exists, otherwise null
060         * @throws Exception if there is a problem accessing the store
061         */
062        Tag lookup( long revision ) throws Exception;
063        
064        /**
065         * Checks to see if a snapshot exists for a specific revision. 
066         *
067         * @param revision the revision number to use to check for a snapshot
068         * @return true if a snapshot exists at the revision, false otherwise
069         * @throws Exception if there is a problem accessing the store
070         */
071        boolean has( long revision ) throws Exception;
072    
073    
074        // -----------------------------------------------------------------------
075        // Tag Search Operations
076        // -----------------------------------------------------------------------
077    
078        
079        /**
080         * Finds all the snapshot tags taken since revision 0 until the current 
081         * revision.
082         *
083         * @param order the revision order in which to return snapshot tags 
084         * @return a cursor containing the tags of all snapshots taken since revision 1
085         * @throws Exception if there is a problem accessing the store
086         */
087        Cursor<Tag> find( RevisionOrder order ) throws Exception;
088        
089        /**
090         * Finds all the snapshot tags taken before a specific revision.  If a tag 
091         * exists at the revision parameter it will be returned as well.
092         *
093         * @param revision the revision number to get snapshots before 
094         * @param order the revision order in which to return snapshot tags 
095         * @return an enumeration over the tags of all snapshots taken before a revision inclusive
096         * @throws Exception if there is a problem accessing the store
097         * @throws IllegalArgumentException if the revision is greater than the current revision
098         * or less than 0.
099         */
100        Cursor<Tag> findBefore( long revision, RevisionOrder order ) throws Exception;
101        
102        /**
103         * Finds all the snapshot tags taken after a specific revision.  If a tag 
104         * exists at the revision parameter it will be returned as well.
105         *
106         * @param revision the revision number to get snapshots after
107         * @param order the revision order in which to return snapshot tags 
108         * @return an enumeration over the tags of all snapshots taken after a revision inclusive
109         * @throws Exception if there is a problem accessing the store
110         * @throws IllegalArgumentException if the revision is greater than the current revision
111         * or less than 0.
112         */
113        Cursor<Tag> findAfter( long revision, RevisionOrder order ) throws Exception;
114        
115        /**
116         * Enumerates over the tags of all snapshots taken between a specific revision 
117         * range inclusive.  The first revision parameter should be less than or equal 
118         * to the second revision parameter.
119         *
120         * @param startRevision the revision to start on inclusive
121         * @param endRevision the revision to end on inclusive
122         * @param order the revision order in which to return snapshot tags
123         * @return enumeration over all the snapshots taken in a revision range inclusive
124         * @throws Exception if there is a problem accessing the store
125         * @throws IllegalArgumentException if the revision range is not constructed properly
126         * or if either revision number is greater than the current revision or less than 0.
127         */
128        Cursor<Tag> find( long startRevision, long endRevision, RevisionOrder order ) 
129            throws Exception;
130    }