001/*
002 * (C) Copyright 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Nuxeo - initial API and implementation
018 *
019 * $Id$
020 */
021
022package org.nuxeo.runtime.model;
023
024import java.io.Serializable;
025
026import org.w3c.dom.Element;
027
028/**
029 * A component extension.
030 * <p>
031 * Extension objects holds extension data as a DOM element.
032 * <p>
033 * This data can be used by the extension point to extract contribution objects by using
034 * {@link org.nuxeo.common.xmap.XMap} XML mapping engine.
035 *
036 * @author <a href="mailto:[email protected]">Bogdan Stefanescu</a>
037 */
038public interface Extension extends Serializable {
039
040    /**
041     * Gets the component name where this extension should be contributed.
042     *
043     * @return the target component name
044     */
045    ComponentName getTargetComponent();
046
047    /**
048     * Gets the extension point name where this extension should be contributed.
049     *
050     * @return the target extension point
051     */
052    String getExtensionPoint();
053
054    /**
055     * Disposes this extension.
056     * <p>
057     * This will erase any data held by the extension.
058     */
059    void dispose();
060
061    /**
062     * Gets the DOM element held by this extension.
063     * <p>
064     * The DOM element correspond to the "extension" element in the component XML descriptor.
065     *
066     * @return the DOM element
067     */
068    Element getElement();
069
070    /**
071     * Sets the DOM element that defines this extension.
072     *
073     * @param element the extension DOM element
074     */
075    void setElement(Element element);
076
077    /**
078     * Gets the extension contribution objects.
079     * <p>
080     * These objects are generated by the extension point from the DOM element and then attached to the extension.
081     *
082     * @return the contribution objects or null if none
083     */
084    Object[] getContributions();
085
086    /**
087     * Sets the contribution objects.
088     * <p>
089     * This method is used by the extension point to attach the contribution objects to the extension.
090     *
091     * @param contributions the contribution objects
092     */
093    void setContributions(Object[] contributions);
094
095    /**
096     * Sets the component owning this extension.
097     *
098     * @param component the component instance owning this extension
099     */
100    void setComponent(ComponentInstance component);
101
102    /**
103     * Gets the component instance owning this extension.
104     *
105     * @return the component instance owning this extension
106     */
107    ComponentInstance getComponent();
108
109    /**
110     * Gets the context of the component who contributed this extension.
111     *
112     * @return the extension context
113     */
114    RuntimeContext getContext();
115
116    /**
117     * Identifies the extension inside the contributing component. The id should be unique in the application. It is
118     * recommended to use the following name convention for the ID: 'component_name#contribution_name'.
119     * <p>
120     * The id is never null. If the user is not specifying an ID, one will be generated as follow:
121     * componentName#targetExtensionPoint.randomNumber
122     */
123    String getId();
124
125    /**
126     * Gets any comment on this extension.
127     * <p>
128     * Comments can be used to document extensions.
129     * <p>
130     * Comments should be short because they are stored in memory.
131     */
132    String getDocumentation();
133
134    /**
135     * Gets the XML representation for this extension.
136     */
137    String toXML();
138
139}