| /* |
| * 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.felix.ipojo.extender; |
| |
| import org.apache.felix.ipojo.extender.builder.FactoryBuilder; |
| import org.apache.felix.ipojo.metadata.Element; |
| |
| /** |
| * This service provides a way for users to manage declarations through code. |
| * |
| * Notice that produced declarations are immutable once build. But it is possible to re-use a |
| * builder to share some configuration through instances. |
| * |
| * <pre> |
| * // Obtain the service through the service registry |
| * DeclarationBuilderService service = ... |
| * |
| * // Get a fresh instance builder |
| * DeclarationBuilder builder = service.newInstance("the.full.name.of.the.component.to.instantiate"); |
| * |
| * DeclarationHandle handle = builder.name("a-unique-name") // Make sure name is unique for the expected type |
| * .configure() |
| * .property("a-property", "a-value") |
| * .property("another-property", "another-value") |
| * .build(); |
| * |
| * // Push the InstanceDeclaration service in the registry |
| * handle.publish(); |
| * </pre> |
| * |
| * Except the {@link InstanceBuilder#build()} call, all methods are optional: |
| * <ul> |
| * <li>{@link InstanceBuilder#name(String)}: if no name is provided, |
| * a default one will be generated by iPOJO.</li> |
| * <li>{@link InstanceBuilder#version(String)}: if no version is provided, |
| * the first un-versioned type will be used.</li> |
| * <li>{@link InstanceBuilder#configure()}: if no configuration is required, can be omitted.</li> |
| * <li>{@link InstanceBuilder#type(String)}: can be used to change the <bold>required</bold> component type.</li> |
| * <li>{@link InstanceBuilder#context(org.osgi.framework.BundleContext)}: by default, the bundle context |
| * used to register the created {@link org.apache.felix.ipojo.extender.Declaration} is the one of the |
| * caller. It can be changed though this method.</li> |
| * </ul> |
| * |
| * Once an instance handle has been created, its configuration (name, type, version and properties) is immutable. It can |
| * only be {@linkplain DeclarationHandle#publish() published} (so that the framework will try to instantiate the |
| * instance) or {@linkplain DeclarationHandle#retract() retracted} (framework will remove the instance). |
| * |
| * Notice that all created instances will appear as "coming from" the bundle that requires the |
| * {@link DeclarationBuilderService} service. Just like having a {@literal metadata.xml} file in your |
| * bundle that declares your instances. It is possible to override this default behavior using |
| * {@link InstanceBuilder#context(org.osgi.framework.BundleContext)}. |
| * |
| * @see org.apache.felix.ipojo.extender.InstanceDeclaration |
| * @see org.apache.felix.ipojo.extender.TypeDeclaration |
| * @see org.apache.felix.ipojo.extender.ExtensionDeclaration |
| * @see org.apache.felix.ipojo.extender.InstanceBuilder |
| * @see org.apache.felix.ipojo.extender.ConfigurationBuilder |
| * @see org.apache.felix.ipojo.extender.DeclarationHandle |
| * |
| * @since 1.11.2 |
| */ |
| public interface DeclarationBuilderService { |
| |
| /** |
| * Declares a new anonymous instance of a given type. |
| * Invoking this method is equivalent to invoking <code>{@linkplain #newInstance(String, String) newInstance(type, null)}</code>. |
| * @param type name of the component to be instantiated (cannot be null). |
| * @return a handle usable to publish / retract the declaration. |
| * @see org.apache.felix.ipojo.extender.InstanceDeclaration |
| */ |
| InstanceBuilder newInstance(String type); |
| |
| /** |
| * Declares a new instance of a given type. |
| * Invoking this method is equivalent to invoking <code>{@linkplain #newInstance(String, String, String) newInstance(type, name, null)}</code>. |
| * @param type name of the component to be instantiated. |
| * @param name name of the new instance (can be null) |
| * @return a handle usable to publish / retract the declaration. |
| * @see org.apache.felix.ipojo.extender.InstanceDeclaration |
| */ |
| InstanceBuilder newInstance(String type, String name); |
| |
| /** |
| * Declares a new instance of a given type. |
| * @param type name of the component to be instantiated. |
| * @param name name of the new instance (can be null) |
| * @param version version of the expected type (can be null) |
| * @return a handle usable to publish / retract the declaration. |
| * @see org.apache.felix.ipojo.extender.InstanceDeclaration |
| */ |
| InstanceBuilder newInstance(String type, String name, String version); |
| |
| /** |
| * Declares a new extension (supports new types like {@literal component}, {@literal composite}, {@literal handler}). |
| * @param name name of the type to support (no namespace to be provided) |
| * @param builder associated factory builder |
| * @return a handle usable to publish / retract the declaration. |
| * @see org.apache.felix.ipojo.IPojoFactory |
| * @see org.apache.felix.ipojo.extender.ExtensionDeclaration |
| */ |
| DeclarationHandle newExtension(String name, FactoryBuilder builder); |
| |
| /** |
| * Declares a new type using the given element description. |
| * @param description description of the component type |
| * @return a handle usable to publish / retract the declaration. |
| * @see org.apache.felix.ipojo.extender.TypeDeclaration |
| */ |
| DeclarationHandle newType(Element description); |
| } |