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 2012-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.ds.scripting; 028 029 030 031 import java.util.List; 032 033 import com.unboundid.directory.sdk.common.internal.Reconfigurable; 034 import com.unboundid.directory.sdk.common.types.Entry; 035 import com.unboundid.directory.sdk.ds.config.UncachedAttributeCriteriaConfig; 036 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 037 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext; 038 import com.unboundid.ldap.sdk.Attribute; 039 import com.unboundid.ldap.sdk.LDAPException; 040 import com.unboundid.ldap.sdk.ResultCode; 041 import com.unboundid.util.Extensible; 042 import com.unboundid.util.ThreadSafety; 043 import com.unboundid.util.ThreadSafetyLevel; 044 import com.unboundid.util.args.ArgumentException; 045 import com.unboundid.util.args.ArgumentParser; 046 047 048 049 /** 050 * This class defines an API that must be implemented by scripted extensions 051 * which have the ability to determine which attributes should be stored in the 052 * uncached-id2entry database of a local DB backend, while the remainder of the 053 * entry is stored in the id2entry database. In environments with data sets too 054 * large to fit in available memory, and in which entries have a significant 055 * amount of space consumed by attributes which are not frequently accessed, 056 * this can help the server better use the memory it does have for attributes 057 * that are more likely to be accessed. 058 * <BR> 059 * <H2>Configuring Groovy-Scripted Uncached Attribute Criteria</H2> 060 * In order to configure a scripted uncached attribute criteria object based on 061 * this API and written in the Groovy scripting language, use a command like: 062 * <PRE> 063 * dsconfig create-uncached-attribute-criteria \ 064 * --criteria-name "<I>{criteria-name}</I>" \ 065 * --type groovy-scripted \ 066 * --set enabled:true \ 067 * --set "script-class:<I>{class-name}</I>" \ 068 * --set "script-argument:<I>{name=value}</I>" 069 * </PRE> 070 * where "<I>{handler-name}</I>" is the name to use for the uncached attribute 071 * criteria instance, "<I>{class-name}</I>" is the fully-qualified name of the 072 * Groovy class written using this API, and "<I>{name=value}</I>" represents 073 * name-value pairs for any arguments to provide to the uncached attribute 074 * criteria object. If multiple arguments should be provided to the uncached 075 * attribute criteria, then the 076 * "<CODE>--set script-argument:<I>{name=value}</I></CODE>" 077 * option should be provided multiple times. 078 * 079 * @see com.unboundid.directory.sdk.ds.api.UncachedAttributeCriteria 080 */ 081 @Extensible() 082 @DirectoryServerExtension() 083 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 084 public abstract class ScriptedUncachedAttributeCriteria 085 implements Reconfigurable<UncachedAttributeCriteriaConfig> 086 { 087 /** 088 * Creates a new instance of this uncached attribute criteria. All uncached 089 * attribute criteria implementations must include a default constructor, but 090 * any initialization should generally be done in the 091 * {@code initializeUncachedAttributeCriteria} method. 092 */ 093 public ScriptedUncachedAttributeCriteria() 094 { 095 // No implementation is required. 096 } 097 098 099 100 /** 101 * {@inheritDoc} 102 */ 103 public void defineConfigArguments(final ArgumentParser parser) 104 throws ArgumentException 105 { 106 // No arguments will be allowed by default. 107 } 108 109 110 111 /** 112 * Initializes this uncached attribute criteria. 113 * 114 * @param serverContext A handle to the server context for the server in 115 * which this extension is running. 116 * @param config The general configuration for this uncached 117 * attribute criteria. 118 * @param parser The argument parser which has been initialized from 119 * the configuration for this uncached attribute 120 * criteria. 121 * 122 * @throws LDAPException If a problem occurs while initializing this 123 * uncached attribute criteria. 124 */ 125 public void initializeUncachedAttributeCriteria( 126 final DirectoryServerContext serverContext, 127 final UncachedAttributeCriteriaConfig config, 128 final ArgumentParser parser) 129 throws LDAPException 130 { 131 // No initialization will be performed by default. 132 } 133 134 135 136 /** 137 * {@inheritDoc} 138 */ 139 public boolean isConfigurationAcceptable( 140 final UncachedAttributeCriteriaConfig config, 141 final ArgumentParser parser, 142 final List<String> unacceptableReasons) 143 { 144 // No extended validation will be performed. 145 return true; 146 } 147 148 149 150 /** 151 * {@inheritDoc} 152 */ 153 public ResultCode applyConfiguration( 154 final UncachedAttributeCriteriaConfig config, 155 final ArgumentParser parser, 156 final List<String> adminActionsRequired, 157 final List<String> messages) 158 { 159 // By default, no configuration changes will be applied. If there are any 160 // arguments, then add an admin action message indicating that the extension 161 // needs to be restarted for any changes to take effect. 162 if (! parser.getNamedArguments().isEmpty()) 163 { 164 adminActionsRequired.add( 165 "No configuration change has actually been applied. The new " + 166 "configuration will not take effect until this uncached " + 167 "attribute criteria is disabled and re-enabled or until the " + 168 "server is restarted."); 169 } 170 171 return ResultCode.SUCCESS; 172 } 173 174 175 176 /** 177 * Performs any cleanup which may be necessary when this uncached attribute 178 * criteria instance is to be taken out of service. 179 */ 180 public void finalizeUncachedAttributeCriteria() 181 { 182 // No implementation is required. 183 } 184 185 186 187 /** 188 * Indicates whether the provided attribute should be written into the 189 * uncached-id2entry database rather than into id2entry. 190 * 191 * @param attribute A read-only representation of the attribute for which to 192 * make the determination. 193 * @param entry A read-only representation of the full entry to be 194 * encoded. 195 * 196 * @return {@code true} if the attribute should be written into the 197 * uncached-id2entry database, or {@code false} if it should be 198 * written into the id2entry database. 199 */ 200 public abstract boolean shouldBeUncached(final Attribute attribute, 201 final Entry entry); 202 }