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