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 */ 020package org.apache.directory.server.core.api.changelog; 021 022 023import org.apache.directory.api.ldap.model.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 */ 052public interface TagSearchEngine 053{ 054 /** 055 * Gets the tag for a specific snapshot if that snapshot exists. 056 * 057 * @param revision the revision number to use to check for a snapshot 058 * @return the snapshot at the revision if one exists, otherwise null 059 * @throws Exception if there is a problem accessing the store 060 */ 061 Tag lookup( long revision ) throws Exception; 062 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 * Finds all the snapshot tags taken since revision 0 until the current 080 * revision. 081 * 082 * @param order the revision order in which to return snapshot tags 083 * @return a cursor containing the tags of all snapshots taken since revision 1 084 * @throws Exception if there is a problem accessing the store 085 */ 086 Cursor<Tag> find( RevisionOrder order ) throws Exception; 087 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 /** 104 * Finds all the snapshot tags taken after a specific revision. If a tag 105 * exists at the revision parameter it will be returned as well. 106 * 107 * @param revision the revision number to get snapshots after 108 * @param order the revision order in which to return snapshot tags 109 * @return an enumeration over the tags of all snapshots taken after a revision inclusive 110 * @throws Exception if there is a problem accessing the store 111 * @throws IllegalArgumentException if the revision is greater than the current revision 112 * or less than 0. 113 */ 114 Cursor<Tag> findAfter( long revision, RevisionOrder order ) throws Exception; 115 116 117 /** 118 * Enumerates over the tags of all snapshots taken between a specific revision 119 * range inclusive. The first revision parameter should be less than or equal 120 * to the second revision parameter. 121 * 122 * @param startRevision the revision to start on inclusive 123 * @param endRevision the revision to end on inclusive 124 * @param order the revision order in which to return snapshot tags 125 * @return enumeration over all the snapshots taken in a revision range inclusive 126 * @throws Exception if there is a problem accessing the store 127 * @throws IllegalArgumentException if the revision range is not constructed properly 128 * or if either revision number is greater than the current revision or less than 0. 129 */ 130 Cursor<Tag> find( long startRevision, long endRevision, RevisionOrder order ) 131 throws Exception; 132}