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 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2010-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.ds.api; 028 029 030 031 import java.util.Collections; 032 import java.util.List; 033 import java.util.Map; 034 035 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider; 036 import com.unboundid.directory.sdk.common.internal.Reconfigurable; 037 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension; 038 import com.unboundid.directory.sdk.common.types.Entry; 039 import com.unboundid.directory.sdk.ds.config.UncachedEntryCriteriaConfig; 040 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext; 041 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 042 import com.unboundid.ldap.sdk.LDAPException; 043 import com.unboundid.ldap.sdk.ResultCode; 044 import com.unboundid.util.Extensible; 045 import com.unboundid.util.ThreadSafety; 046 import com.unboundid.util.ThreadSafetyLevel; 047 import com.unboundid.util.args.ArgumentException; 048 import com.unboundid.util.args.ArgumentParser; 049 050 051 052 /** 053 * This class defines an API that must be implemented by extensions which have 054 * the ability to determine which entries should be stored in the 055 * uncached-id2entry database of a local DB backend, rather than in the id2entry 056 * database. In environments with data sets too large to fit in available 057 * memory, this can help the server better use the memory it does have for 058 * entries that are more likely to be accessed. 059 * <BR> 060 * <H2>Configuring Uncached Entry Criteria</H2> 061 * In order to configure an uncached entry criteria object created using this 062 * API, use a command like: 063 * <PRE> 064 * dsconfig create-uncached-entry-criteria \ 065 * --criteria-name "<I>{criteria-name}</I>" \ 066 * --type third-party \ 067 * --set enabled:true \ 068 * --set "extension-class:<I>{class-name}</I>" \ 069 * --set "extension-argument:<I>{name=value}</I>" 070 * </PRE> 071 * where "<I>{criteria-name}</I>" is the name to use for the uncached entry 072 * criteria instance, "<I>{class-name}</I>" is the fully-qualified name of the 073 * Java class that extends 074 * {@code com.unboundid.directory.sdk.ds.api.UncachedEntryCriteria}, 075 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to 076 * provide to the uncached entry criteria. If multiple arguments 077 * should be provided to the criteria, then the 078 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be 079 * provided multiple times. 080 * 081 * 082 * @see com.unboundid.directory.sdk.ds.scripting.ScriptedUncachedEntryCriteria 083 */ 084 @Extensible() 085 @DirectoryServerExtension() 086 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 087 public abstract class UncachedEntryCriteria 088 implements UnboundIDExtension, 089 Reconfigurable<UncachedEntryCriteriaConfig>, 090 ExampleUsageProvider 091 { 092 /** 093 * Creates a new instance of this uncached entry criteria. All uncached entry 094 * criteria implementations must include a default constructor, but any 095 * initialization should generally be done in the 096 * {@code initializeUncachedEntryCriteria} method. 097 */ 098 public UncachedEntryCriteria() 099 { 100 // No implementation is required. 101 } 102 103 104 105 /** 106 * {@inheritDoc} 107 */ 108 public abstract String getExtensionName(); 109 110 111 112 /** 113 * {@inheritDoc} 114 */ 115 public abstract String[] getExtensionDescription(); 116 117 118 119 /** 120 * {@inheritDoc} 121 */ 122 public void defineConfigArguments(final ArgumentParser parser) 123 throws ArgumentException 124 { 125 // No arguments will be allowed by default. 126 } 127 128 129 130 /** 131 * Initializes this uncached entry criteria. 132 * 133 * @param serverContext A handle to the server context for the server in 134 * which this extension is running. 135 * @param config The general configuration for this uncached entry 136 * criteria. 137 * @param parser The argument parser which has been initialized from 138 * the configuration for this uncached entry criteria. 139 * 140 * @throws LDAPException If a problem occurs while initializing this 141 * uncached entry criteria. 142 */ 143 public void initializeUncachedEntryCriteria( 144 final DirectoryServerContext serverContext, 145 final UncachedEntryCriteriaConfig config, 146 final ArgumentParser parser) 147 throws LDAPException 148 { 149 // No initialization will be performed by default. 150 } 151 152 153 154 /** 155 * {@inheritDoc} 156 */ 157 public boolean isConfigurationAcceptable( 158 final UncachedEntryCriteriaConfig config, 159 final ArgumentParser parser, 160 final List<String> unacceptableReasons) 161 { 162 // No extended validation will be performed by default. 163 return true; 164 } 165 166 167 168 /** 169 * {@inheritDoc} 170 */ 171 public ResultCode applyConfiguration( 172 final UncachedEntryCriteriaConfig config, 173 final ArgumentParser parser, 174 final List<String> adminActionsRequired, 175 final List<String> messages) 176 { 177 // By default, no configuration changes will be applied. If there are any 178 // arguments, then add an admin action message indicating that the extension 179 // needs to be restarted for any changes to take effect. 180 if (! parser.getNamedArguments().isEmpty()) 181 { 182 adminActionsRequired.add( 183 "No configuration change has actually been applied. The new " + 184 "configuration will not take effect until this uncached " + 185 "entry criteria is disabled and re-enabled or until the " + 186 "server is restarted."); 187 } 188 189 return ResultCode.SUCCESS; 190 } 191 192 193 194 /** 195 * Performs any cleanup which may be necessary when this uncached entry 196 * criteria instance is to be taken out of service. 197 */ 198 public void finalizeUncachedEntryCriteria() 199 { 200 // No implementation is required. 201 } 202 203 204 205 /** 206 * Indicates whether the provided entry should be written into the 207 * uncached-id2entry database rather than into id2entry. This method may be 208 * used both for new entries (e.g., from add operations or LDIF imports) or 209 * existing entries (e.g., from modify, modify DN, or soft delete operations, 210 * or from re-encode processing). 211 * 212 * @param previousEntry A read-only representation of the entry as it 213 * existed before the update. If the entry is 214 * unchanged or did not previously exist, then this 215 * will be the same as {@code updatedEntry}. 216 * @param updatedEntry A read-only representation of the entry as it will 217 * be written into either the id2entry or 218 * uncached-id2entry database. 219 * 220 * @return {@code true} if the entry should be written into the 221 * uncached-id2entry database, or {@code false} if it should be 222 * written into the id2entry database. 223 */ 224 public abstract boolean shouldBeUncached(final Entry previousEntry, 225 final Entry updatedEntry); 226 227 228 229 /** 230 * {@inheritDoc} 231 */ 232 public Map<List<String>,String> getExamplesArgumentSets() 233 { 234 return Collections.emptyMap(); 235 } 236 }