001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2009 Sun Microsystems, Inc. 015 * Portions copyright 2014-2015 ForgeRock AS. 016 */ 017package org.forgerock.opendj.ldap.schema; 018 019import java.util.Collection; 020import java.util.List; 021 022import org.forgerock.opendj.ldap.Assertion; 023import org.forgerock.opendj.ldap.ByteSequence; 024import org.forgerock.opendj.ldap.ByteString; 025import org.forgerock.opendj.ldap.DecodeException; 026import org.forgerock.opendj.ldap.spi.Indexer; 027import org.forgerock.opendj.ldap.spi.IndexingOptions; 028 029/** 030 * This interface defines the set of methods that must be implemented to define 031 * a new matching rule. 032 */ 033public interface MatchingRuleImpl { 034 035 /** 036 * Retrieves the normalized form of the provided assertion value, which is 037 * best suited for efficiently performing less than matching operations on 038 * that value. The assertion value is guaranteed to be valid against this 039 * matching rule's assertion syntax. 040 * 041 * @param schema 042 * The schema in which this matching rule is defined. 043 * @param assertionValue 044 * The syntax checked assertion value to be normalized. 045 * @return The normalized version of the provided assertion value. 046 * @throws DecodeException 047 * if an syntax error occurred while parsing the value. 048 */ 049 Assertion getAssertion(Schema schema, ByteSequence assertionValue) throws DecodeException; 050 051 /** 052 * Retrieves the normalized form of the provided assertion substring values, 053 * which is best suited for efficiently performing matching operations on 054 * that value. 055 * 056 * @param schema 057 * The schema in which this matching rule is defined. 058 * @param subInitial 059 * The normalized substring value fragment that should appear at 060 * the beginning of the target value. 061 * @param subAnyElements 062 * The normalized substring value fragments that should appear in 063 * the middle of the target value. 064 * @param subFinal 065 * The normalized substring value fragment that should appear at 066 * the end of the target value. 067 * @return The normalized version of the provided assertion value. 068 * @throws DecodeException 069 * if an syntax error occurred while parsing the value. 070 */ 071 Assertion getSubstringAssertion(Schema schema, ByteSequence subInitial, 072 List<? extends ByteSequence> subAnyElements, ByteSequence subFinal) 073 throws DecodeException; 074 075 /** 076 * Retrieves the normalized form of the provided assertion value, which is 077 * best suited for efficiently performing greater than or equal matching 078 * operations on that value. The assertion value is guaranteed to be valid 079 * against this matching rule's assertion syntax. 080 * 081 * @param schema 082 * The schema in which this matching rule is defined. 083 * @param value 084 * The syntax checked assertion value to be normalized. 085 * @return The normalized version of the provided assertion value. 086 * @throws DecodeException 087 * if an syntax error occurred while parsing the value. 088 */ 089 Assertion getGreaterOrEqualAssertion(Schema schema, ByteSequence value) throws DecodeException; 090 091 /** 092 * Retrieves the normalized form of the provided assertion value, which is 093 * best suited for efficiently performing less than or equal matching 094 * operations on that value. The assertion value is guaranteed to be valid 095 * against this matching rule's assertion syntax. 096 * 097 * @param schema 098 * The schema in which this matching rule is defined. 099 * @param value 100 * The syntax checked assertion value to be normalized. 101 * @return The normalized version of the provided assertion value. 102 * @throws DecodeException 103 * if an syntax error occurred while parsing the value. 104 */ 105 Assertion getLessOrEqualAssertion(Schema schema, ByteSequence value) throws DecodeException; 106 107 /** 108 * Retrieves the normalized form of the provided attribute value, which is 109 * best suited for efficiently performing matching operations on that value. 110 * Equality and ordering matching rules should return a normalized 111 * representation which can be compared with other normalized values using 112 * {@link ByteSequence#equals(Object)} and 113 * {@link ByteSequence#compareTo(ByteSequence)}. 114 * 115 * @param schema 116 * The schema in which this matching rule is defined. 117 * @param value 118 * The attribute value to be normalized. 119 * @return The normalized version of the provided attribute value. 120 * @throws DecodeException 121 * If an syntax error occurred while parsing the value. 122 */ 123 ByteString normalizeAttributeValue(Schema schema, ByteSequence value) throws DecodeException; 124 125 /** 126 * Returns the indexers for this matching rule. 127 * @param options 128 * The indexing options 129 * @return a non null collection of indexers for this matching rule. 130 */ 131 Collection<? extends Indexer> createIndexers(IndexingOptions options); 132}