| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| package org.apache.openjpa.lib.instrumentation; |
| |
| import java.util.Set; |
| |
| import org.apache.openjpa.lib.conf.Configuration; |
| |
| /** |
| * Pluggable instrumentation providers (ex. JMX) must implement this interface. It |
| * provides methods for controlling the provider and the instruments instrumented |
| * by the provider. |
| */ |
| public interface InstrumentationProvider { |
| |
| /** |
| * Whether the instrumentation provider started |
| * @return true if the provider is started |
| */ |
| boolean isStarted(); |
| /** |
| * Starts the instrumentation provider |
| */ |
| void stop(); |
| |
| /** |
| * Stops the instrumentation provider |
| */ |
| void start(); |
| |
| /** |
| * Gets the configuration associated with the instrumentation provider |
| * @return the configuration associated with the provider |
| */ |
| Configuration getConfiguration(); |
| |
| /** |
| * Used to associate one or more instruments to a provider. Instruments |
| * are specified by class name or alias. Multiple instruments must be |
| * specified as a comma separated list. |
| * |
| * example: DataCache,QueryCache,com.my.MyInstrument |
| * where DataCache and QueryCache have aliases and com.my.MyInstrument is |
| * a class implementing an Instrument. |
| * |
| * @param instruments one or more instrument class names or aliases |
| */ |
| void setInstrument(String instruments); |
| |
| /** |
| * Returns the string-based list of instruments directly configured by |
| * this provider via setInstrument. |
| */ |
| String getInstrument(); |
| |
| /** |
| * Sets configuration options for this provider |
| * @param options |
| */ |
| void setOptions(String options); |
| |
| /** |
| * Gets configuration options for this provider |
| * @param options |
| */ |
| String getOptions(); |
| |
| /** |
| * Returns an string array of identifier to class name aliases for |
| * instruments known to the instrumentation provider. Example: |
| * |
| * {"DataCache", "org.apache.openjpa.instrumentation.DataCacheInstrument", |
| * "QueryCache", "org.apache.openjpa.instrumentation.QueryCacheInstrument"} |
| * @return a string array of identifier, class name pairs. |
| */ |
| String[] getInstrumentAliases(); |
| |
| /** |
| * Adds an instrument to this providers list of managed instruments. The |
| * instrument will participate in context-based lifecycle routines, |
| * depending on the instrumentation level. |
| * @param instrument |
| */ |
| void addInstrument(Instrument instrument); |
| |
| /** |
| * Stops all instruments of the specified instrumentation level and context. |
| * @param level instrumentation level |
| * @param context instrumentation context (factory, broker, config) |
| */ |
| void stopInstruments(InstrumentationLevel level, Object context); |
| |
| /** |
| * Starts all instruments of the specified instrumentation level and context. |
| * @param level instrumentation level |
| * @param context instrumentation context (factory, broker, config) |
| */ |
| void startInstruments(InstrumentationLevel level, Object context); |
| |
| /** |
| * Initializes an instrument within the provided context. |
| * @param instrument an instrument |
| * @param context instrumentation context (factory, broker, config) |
| */ |
| void initializeInstrument(Instrument instrument, Object context); |
| |
| /** |
| * Initializes an instrument within the provided options and context. |
| * @param instrument an instrument |
| * @param options configuration options to provide the instrument during initialization |
| * @param context instrumentation context (factory, broker, config) |
| */ |
| void initializeInstrument(Instrument instrument, String options, Object context); |
| |
| /** |
| * Returns an instrument instrumented by this provider by name |
| * @param name the name of the instrument to return |
| * @return the instrument or null if not instrumented by this provider |
| */ |
| Instrument getInstrumentByName(String name); |
| |
| /** |
| * Removes an instrument instrumented by this provider by name |
| * @param name the name of the instrument to remove |
| */ |
| void removeInstrumentByName(String name); |
| |
| /** |
| * Gets all instruments instrumented by this provider |
| * @return instruments instrumented by this provider |
| */ |
| Set<Instrument> getInstruments(); |
| |
| /** |
| * Starts an instrument |
| * @param instrument this instrument to start |
| */ |
| void startInstrument(Instrument instrument); |
| |
| /** |
| * Stops an instrument |
| * @param instrument the instrument to stop |
| */ |
| void stopInstrument(Instrument instrument); |
| |
| /** |
| * Stops an instrument, forcing the stop, if necessary. |
| * @param instrument the instrument to stop |
| * @param force forces the stop if the instrument does not stop gracefully. |
| */ |
| void stopInstrument(Instrument instrument, boolean force); |
| } |