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