| /******************************************************************************* |
| * Copyright (c) 2004, 2016 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| |
| package org.eclipse.ui.internal.intro.impl.model; |
| |
| import java.util.Iterator; |
| import java.util.Vector; |
| |
| import org.eclipse.core.runtime.IConfigurationElement; |
| import org.eclipse.help.UAContentFilter; |
| import org.eclipse.help.internal.UAElementFactory; |
| import org.eclipse.ui.internal.intro.impl.model.loader.ExtensionPointManager; |
| import org.eclipse.ui.internal.intro.impl.util.IntroEvaluationContext; |
| import org.eclipse.ui.internal.intro.impl.util.Log; |
| import org.eclipse.ui.internal.intro.impl.util.StringUtil; |
| import org.osgi.framework.Bundle; |
| import org.w3c.dom.Element; |
| import org.w3c.dom.Node; |
| import org.w3c.dom.NodeList; |
| |
| /** |
| * An intro config component that is a container, ie: it can have children. |
| */ |
| public abstract class AbstractIntroContainer extends AbstractBaseIntroElement { |
| |
| protected static final String ATT_BG_IMAGE = "bgImage"; //$NON-NLS-1$ |
| // vector is lazily created when children are loaded in a call to |
| // loadChildren(). |
| protected Vector<AbstractIntroElement> children; |
| protected boolean loaded = false; |
| protected boolean resolved = false; |
| protected Element element; |
| |
| // store the base since it will needed later to resolve children. |
| protected String base; |
| |
| /** |
| * @param element |
| */ |
| AbstractIntroContainer(IConfigurationElement element) { |
| super(element); |
| } |
| |
| /** |
| * @param element |
| */ |
| AbstractIntroContainer(Element element, Bundle bundle) { |
| super(element, bundle); |
| this.element = element; |
| } |
| |
| /** |
| * @param element |
| */ |
| AbstractIntroContainer(Element element, Bundle bundle, String base) { |
| super(element, bundle); |
| this.element = element; |
| this.base = base; |
| } |
| |
| |
| /** |
| * Get the children of this container. Loading children and resolving |
| * includes and extension is delayed until this method call. |
| * |
| * @return Returns all the children of this container. |
| */ |
| public AbstractIntroElement[] getChildren() { |
| if (!loaded) |
| loadChildren(); |
| |
| if (!loaded) |
| // if loaded still is false, something went wrong. This could happen |
| // when loading content from another external content files. |
| return new AbstractIntroElement[0]; |
| |
| if (!resolved) |
| resolveChildren(); |
| |
| Vector filtered = filterChildren(children); |
| |
| AbstractIntroElement[] childrenElements = (AbstractIntroElement[]) convertToModelArray( |
| filtered, AbstractIntroElement.ELEMENT); |
| return childrenElements; |
| } |
| |
| /** |
| * Returns all the children of this container that are of the specified |
| * type(s). <br> |
| * An example of an element mask is as follows: |
| * <p> |
| * <code> |
| * int elementMask = IntroElement.IMAGE | IntroElement.DEFAULT_LINK; |
| * int elementMask = IntroElement.ABSTRACT_CONTAINER; |
| * </code> |
| * The return type is determined depending on the mask. If the mask is a |
| * predefined constant in the IntroElement, and it does not correspond to an |
| * abstract model class, then the object returned can be safely cast to an |
| * array of the corresponding model class. For exmaple, the following code |
| * gets all groups in the given page, in the same order they appear in the |
| * plugin.xml markup: |
| * <p> |
| * <code> |
| * Introgroup[] groups = (IntroGroup[])page.getChildrenOfType(IntroElement.GROUP); |
| * </code> |
| * |
| * However, if the element mask is not homogenous (for example: LINKS | |
| * GROUP) then the returned array must be cast to an array of |
| * IntroElements.For exmaple, the following code gets all images and links |
| * in the given page, in the same order they appear in the plugin.xml |
| * markup: |
| * <p> |
| * <code> |
| * int elementMask = IntroElement.IMAGE | IntroElement.DEFAULT_LINK; |
| * IntroElement[] imagesAndLinks = |
| * (IntroElement[])page.getChildrenOfType(elementMask); |
| * </code> |
| * |
| * @return An array of elements of the right type. If the container has no |
| * children, or no children of the specified types, returns an empty |
| * array. |
| */ |
| public Object[] getChildrenOfType(int elementMask) { |
| |
| AbstractIntroElement[] childrenElements = getChildren(); |
| // if we have no children, we still need to return an empty array of |
| // the correct type. |
| Vector<AbstractIntroElement> typedChildren = new Vector<>(); |
| for (int i = 0; i < childrenElements.length; i++) { |
| AbstractIntroElement element = childrenElements[i]; |
| if (element.isOfType(elementMask)) |
| typedChildren.addElement(element); |
| } |
| return convertToModelArray(typedChildren, elementMask); |
| } |
| |
| /** |
| * Utility method to convert all the content of a vector of |
| * AbstractIntroElements into an array of IntroElements cast to the correct |
| * class type. It is assumed that all elements in this vector are |
| * IntroElement instances. If elementMask is a predefined model type (ie: |
| * homogenous), then return array of corresponding type. Else, returns an |
| * array of IntroElements. |
| * |
| * @param vector |
| */ |
| private Object[] convertToModelArray(Vector vector, int elementMask) { |
| int size = vector.size(); |
| Object[] src = null; |
| switch (elementMask) { |
| // homogenous vector. |
| case AbstractIntroElement.GROUP: |
| src = new IntroGroup[size]; |
| break; |
| case AbstractIntroElement.LINK: |
| src = new IntroLink[size]; |
| break; |
| case AbstractIntroElement.TEXT: |
| src = new IntroText[size]; |
| break; |
| case AbstractIntroElement.IMAGE: |
| src = new IntroImage[size]; |
| break; |
| case AbstractIntroElement.HR: |
| src = new IntroSeparator[size]; |
| break; |
| case AbstractIntroElement.HTML: |
| src = new IntroHTML[size]; |
| break; |
| case AbstractIntroElement.INCLUDE: |
| src = new IntroInclude[size]; |
| break; |
| case AbstractIntroElement.PAGE: |
| src = new IntroPage[size]; |
| break; |
| case AbstractIntroElement.ABSTRACT_PAGE: |
| src = new AbstractIntroPage[size]; |
| break; |
| case AbstractIntroElement.ABSTRACT_CONTAINER: |
| src = new AbstractIntroContainer[size]; |
| break; |
| case AbstractIntroElement.HEAD: |
| src = new IntroHead[size]; |
| break; |
| case AbstractIntroElement.PAGE_TITLE: |
| src = new IntroPageTitle[size]; |
| break; |
| case AbstractIntroElement.ANCHOR: |
| src = new IntroAnchor[size]; |
| break; |
| case AbstractIntroElement.CONTENT_PROVIDER: |
| src = new IntroContentProvider[size]; |
| break; |
| |
| default: |
| // now handle left over abstract types. Vector is not homogenous. |
| src = new AbstractIntroElement[size]; |
| break; |
| } |
| |
| vector.copyInto(src); |
| return src; |
| |
| } |
| |
| /** |
| * Load all the children of this container. A container can have other |
| * containers, links, htmls, text, image, include. Load them in the order |
| * they appear in the xml content file. |
| */ |
| protected void loadChildren() { |
| // init the children vector. old children are disposed automatically. |
| children = new Vector<>(); |
| |
| |
| NodeList nodeList = element.getChildNodes(); |
| Vector<Node> vector = new Vector<>(); |
| for (int i = 0; i < nodeList.getLength(); i++) { |
| Node node = nodeList.item(i); |
| if (node.getNodeType() == Node.ELEMENT_NODE) |
| vector.add(node); |
| } |
| Element[] filteredElements = new Element[vector.size()]; |
| vector.copyInto(filteredElements); |
| // add the elements at the end children's vector. |
| insertElementsBefore(filteredElements, getBundle(), base, children |
| .size(), null); |
| loaded = true; |
| // we cannot free DOM model element because a page's children may be |
| // nulled when reflowing a content provider. |
| } |
| |
| /** |
| * Adds the given elements as children of this container, before the |
| * specified index. |
| * |
| * @param childElements |
| */ |
| protected void insertElementsBefore(Element[] childElements, Bundle bundle, |
| String base, int index, String mixinStyle) { |
| for (int i = 0; i < childElements.length; i++) { |
| Element childElement = childElements[i]; |
| AbstractIntroElement child = getModelChild(childElement, bundle, |
| base); |
| if (child != null) { |
| child.setParent(this); |
| child.setMixinStyle(mixinStyle); |
| children.add(index, child); |
| // index is only incremented if we actually added a child. |
| index++; |
| } |
| } |
| } |
| |
| /** |
| * Adds the given elements as children of this container, before the |
| * specified element. The element must be a direct child of this container. |
| * |
| * @param childElements |
| */ |
| protected void insertElementsBefore(Element[] childElements, Bundle bundle, |
| String base, AbstractIntroElement child, String mixinStyle) { |
| int childLocation = children.indexOf(child); |
| if (childLocation == -1) |
| // bad reference child. |
| return; |
| insertElementsBefore(childElements, bundle, base, childLocation, mixinStyle); |
| } |
| |
| |
| |
| /** |
| * Adds a child to this container, depending on its type. Subclasses may |
| * override if there is a child specific to the subclass. |
| * |
| * @param childElements |
| */ |
| protected AbstractIntroElement getModelChild(Element childElement, |
| Bundle bundle, String base) { |
| |
| AbstractIntroElement child = null; |
| if (childElement.getNodeName().equalsIgnoreCase(IntroGroup.TAG_GROUP)) |
| child = new IntroGroup(childElement, bundle, base); |
| else if (childElement.getNodeName() |
| .equalsIgnoreCase(IntroLink.TAG_LINK)) |
| child = new IntroLink(childElement, bundle, base); |
| else if (childElement.getNodeName() |
| .equalsIgnoreCase(IntroText.TAG_TEXT)) |
| child = new IntroText(childElement, bundle); |
| else if (childElement.getNodeName().equalsIgnoreCase( |
| IntroImage.TAG_IMAGE)) |
| child = new IntroImage(childElement, bundle, base); |
| else if (childElement.getNodeName().equalsIgnoreCase( |
| IntroSeparator.TAG_HR)) |
| child = new IntroSeparator(childElement, bundle, base); |
| else if (childElement.getNodeName() |
| .equalsIgnoreCase(IntroHTML.TAG_HTML)) |
| child = new IntroHTML(childElement, bundle, base); |
| else if (childElement.getNodeName().equalsIgnoreCase( |
| IntroInclude.TAG_INCLUDE)) |
| child = new IntroInclude(childElement, bundle); |
| else if (childElement.getNodeName().equalsIgnoreCase( |
| IntroAnchor.TAG_ANCHOR)) |
| child = new IntroAnchor(childElement, bundle); |
| else if (childElement.getNodeName().equalsIgnoreCase( |
| IntroContentProvider.TAG_CONTENT_PROVIDER)) |
| child = new IntroContentProvider(childElement, bundle); |
| return child; |
| } |
| |
| |
| /** |
| * Resolve each include in this container's children. Includes are lazily |
| * resolved on a per container basis, when the container is resolved. |
| */ |
| protected void resolveChildren() { |
| AbstractIntroElement[] array = (AbstractIntroElement[])children.toArray(new AbstractIntroElement[children.size()]); |
| for (int i=0;i<array.length;++i) { |
| AbstractIntroElement child = array[i]; |
| if (UAContentFilter.isFiltered(UAElementFactory.newElement(child.getElement()), IntroEvaluationContext.getContext())) { |
| children.remove(child); |
| } |
| else if (child.getType() == AbstractIntroElement.INCLUDE) { |
| resolveInclude((IntroInclude) child); |
| } |
| } |
| resolved = true; |
| } |
| |
| /** |
| * Resolves an include. Gets the intro element pointed to by the include, |
| * and adds it as a child of this current container. If target is not a |
| * group, or any element that can be included in a group, ignore this |
| * include. |
| * |
| * @param include |
| */ |
| private void resolveInclude(IntroInclude include) { |
| AbstractIntroElement target = findIncludeTarget(include); |
| if (target == null) |
| // target could not be found. |
| return; |
| if (target.isOfType(AbstractIntroElement.GROUP |
| | AbstractIntroElement.ABSTRACT_TEXT |
| | AbstractIntroElement.IMAGE | AbstractIntroElement.TEXT |
| | AbstractIntroElement.PAGE_TITLE)) |
| // be picky about model elements to include. Can not use |
| // BASE_ELEMENT model class because pages can not be included. |
| insertTarget(include, target); |
| } |
| |
| /** |
| * Filters the appropriate elements from the given Vector, according to the current |
| * environment. For example, if one of the elements has a tag to filter for os=linux and |
| * the os is win32, the element will not be returned in the resulting Vector. |
| * |
| * @param unfiltered the unfiltered elements |
| * @return a new Vector with elements filtered |
| */ |
| private <T> Vector<T> filterChildren(Vector<T> unfiltered) { |
| Vector<T> filtered = new Vector<>(); |
| Iterator<T> iter = unfiltered.iterator(); |
| while (iter.hasNext()) { |
| T element = iter.next(); |
| if (!UAContentFilter.isFiltered(element, IntroEvaluationContext.getContext())) { |
| filtered.add(element); |
| } |
| } |
| return filtered; |
| } |
| |
| /** |
| * Find the target element pointed to by the path in the include. It is |
| * assumed that configId always points to an external config, and not the |
| * same config of the inlcude. |
| * |
| * @param include |
| * @param path |
| * @return |
| */ |
| private AbstractIntroElement findIncludeTarget(IntroInclude include) { |
| String path = include.getPath(); |
| IntroModelRoot targetModelRoot = (IntroModelRoot) getParentPage() |
| .getParent(); |
| String targetConfigID = include.getConfigId(); |
| if (targetConfigID != null) |
| targetModelRoot = ExtensionPointManager.getInst().getModel( |
| targetConfigID); |
| if (targetModelRoot == null) |
| // if the target config was not found, skip this include. |
| return null; |
| AbstractIntroElement target = findTarget(targetModelRoot, path); |
| return target; |
| } |
| |
| /** |
| * Finds the child element that corresponds to the given path in the passed |
| * model.<br> |
| * ps: This method could be a static method, but left as instance for model |
| * enhancements. |
| * |
| * @param model |
| * @param path |
| * @return |
| */ |
| public AbstractIntroElement findTarget(AbstractIntroContainer container, |
| String path) { |
| // extract path segments. Get first segment to start search. |
| String[] pathSegments = StringUtil.split(path, "/"); //$NON-NLS-1$ |
| if (container == null) |
| return null; |
| |
| AbstractIntroElement target = container.findChild(pathSegments[0]); |
| if (target == null) |
| // there is no direct child with the specified first path segment. |
| return null; |
| |
| // found parent segment. now find each child segment. |
| for (int i = 1; i < pathSegments.length; i++) { |
| if (!(target instanceof AbstractIntroContainer)) { |
| // parent is not a container, so no point going on. |
| return null; |
| } |
| String pathSegment = pathSegments[i]; |
| target = ((AbstractIntroContainer) target).findChild(pathSegment); |
| if (target == null) |
| // tried to find next segment and failed. |
| return null; |
| } |
| return target; |
| } |
| |
| public AbstractIntroElement findTarget(AbstractIntroContainer container, |
| String path, String extensionId) { |
| // resolve path segments if they are incomplete. |
| if (path.indexOf("@")!= -1) { //$NON-NLS-1$ |
| // new in 3.2: dynamic resolution of incomplete target paths |
| IntroModelRoot root = getModelRoot(); |
| if (root!=null) { |
| path = root.resolvePath(extensionId, path); |
| if (path==null) |
| return null; |
| } |
| |
| } |
| return this.findTarget(container, path); |
| } |
| |
| |
| public AbstractIntroElement findTarget(String path) { |
| return findTarget(this, path); |
| } |
| |
| |
| |
| /* |
| * searches direct children for the first child with the given id. The type |
| * of the child can be any model element that has an id. ie: |
| * AbstractIntroIdElement |
| * |
| * @see org.eclipse.ui.internal.intro.impl.model.IntroElement#getType() |
| */ |
| public AbstractIntroElement findChild(String elementId) { |
| return findChild(elementId, ID_ELEMENT); |
| } |
| |
| /* |
| * searches direct children for the first child with the given id. The type |
| * of the child must be of the passed model types mask. This method handles |
| * the 3.0 style model for content. Pages enhance this behavior with DOM |
| * apis. |
| * |
| * @see org.eclipse.ui.internal.intro.impl.model.IntroElement#getType() |
| */ |
| public AbstractIntroElement findChild(String elementId, int elementMask) { |
| if (!loaded) |
| loadChildren(); |
| |
| for (int i = 0; i < children.size(); i++) { |
| AbstractIntroElement aChild = (AbstractIntroElement) children |
| .elementAt(i); |
| if (!aChild.isOfType(ID_ELEMENT)) |
| // includes and heads do not have ids, and so can not be |
| // referenced directly. This means that they can not be |
| // targets for other includes. Skip, just in case someone |
| // adds an id to it! Also, this applies to all elements in |
| // the model that do not have ids. |
| continue; |
| AbstractIntroIdElement child = (AbstractIntroIdElement) aChild; |
| if (child.getId() != null && child.getId().equals(elementId) |
| && child.isOfType(elementMask)) |
| return child; |
| } |
| // no child with given id and type found. |
| return null; |
| } |
| |
| |
| |
| private void insertTarget(IntroInclude include, AbstractIntroElement target) { |
| int includeLocation = children.indexOf(include); |
| if (includeLocation == -1) |
| // should never be here. |
| return; |
| children.remove(includeLocation); |
| // handle merging target styles first, before changing target parent to |
| // enable inheritance of styles. |
| handleIncludeStyleInheritence(include, target); |
| // now clone the target node because original model should be kept |
| // intact. |
| AbstractIntroElement clonedTarget = null; |
| try { |
| clonedTarget = (AbstractIntroElement) target.clone(); |
| } catch (CloneNotSupportedException ex) { |
| // should never be here. |
| Log.error("Failed to clone Intro model node.", ex); //$NON-NLS-1$ |
| return; |
| } |
| // set parent of cloned target to be this container. |
| clonedTarget.setParent(this); |
| children.insertElementAt(clonedTarget, includeLocation); |
| } |
| |
| /** |
| * Updates the inherited styles based on the merge-style attribute. If we |
| * are including a shared group, or if we are including an element from the |
| * same page, do nothing. For inherited alt-styles, we have to cache the pd |
| * from which we inherited the styles to be able to access resources in that |
| * plugin. Also note that when including a container, it must be resolved |
| * otherwise reparenting will cause includes in this target container to |
| * fail. |
| * |
| * @param include |
| * @param target |
| */ |
| private void handleIncludeStyleInheritence(IntroInclude include, |
| AbstractIntroElement target) { |
| |
| if (include.getMergeStyle() == false) |
| // target styles are not needed. nothing to do. |
| return; |
| |
| if (target.getParent().getType() == AbstractIntroElement.MODEL_ROOT |
| || target.getParentPage().equals(include.getParentPage())) |
| // If we are including from this same page ie: target is in the |
| // same page, OR if we are including a shared group, defined |
| // under a config, do not include styles. |
| return; |
| |
| // Update the parent page styles. skip style if it is null. Note, |
| // include both the target page styles and inherited styles. The full |
| // page styles need to be include. |
| String style = target.getParentPage().getStyle(); |
| if (style != null) |
| getParentPage().addStyle(style); |
| |
| // for alt-style cache bundle for loading resources. |
| style = target.getParentPage().getAltStyle(); |
| if (style != null) { |
| Bundle bundle = target.getBundle(); |
| getParentPage().addAltStyle(style, bundle); |
| } |
| |
| // now add inherited styles. Race condition could happen here if Page A |
| // is including from Page B which is in turn including from Page A. |
| getParentPage().addStyles(target.getParentPage().getStyles()); |
| getParentPage().addAltStyles(target.getParentPage().getAltStyles()); |
| |
| } |
| |
| /** |
| * Creates a clone of the given target node. A clone is create by simply |
| * recreating that protion of the model. |
| * |
| * Note: looked into the clonable interface in Java, but it was not used |
| * because it makes modifications/additions to the model harder to maintain. |
| * Will revisit later. |
| * |
| * @param targer |
| * @return |
| */ |
| protected AbstractIntroElement cloneTarget(AbstractIntroElement target) { |
| return null; |
| } |
| |
| @Override |
| public int getType() { |
| return AbstractIntroElement.ABSTRACT_CONTAINER; |
| } |
| |
| /** |
| * Deep copy since class has mutable objects. Leave DOM element as a shallow |
| * reference copy since DOM is immutable. |
| */ |
| @Override |
| public Object clone() throws CloneNotSupportedException { |
| AbstractIntroContainer clone = (AbstractIntroContainer) super.clone(); |
| clone.children = new Vector<>(); |
| if (children != null) { |
| for (int i = 0; i < children.size(); i++) { |
| AbstractIntroElement cloneChild = (AbstractIntroElement) ((AbstractIntroElement) children |
| .elementAt(i)).clone(); |
| cloneChild.setParent(clone); |
| clone.children.add(i, cloneChild); |
| } |
| } |
| return clone; |
| } |
| |
| /** |
| * Returns the element. |
| * |
| * @return |
| */ |
| @Override |
| public Element getElement() { |
| return this.element; |
| } |
| |
| public String getBase() { |
| return base; |
| } |
| |
| |
| /* |
| * Clears this container. This means emptying the children, and resetting |
| * flags. |
| */ |
| public void clearChildren() { |
| this.children.clear(); |
| } |
| |
| |
| /** |
| * Adds a model element as a child. Caller is responsible for inserting |
| * model elements that rea valid as children. |
| * |
| * @param child |
| */ |
| public void addChild(AbstractIntroElement child) { |
| children.add(child); |
| } |
| |
| public void removeChild(AbstractIntroElement child) { |
| children.remove(child); |
| } |
| |
| public String getBackgroundImage() { |
| return getAttribute(element, ATT_BG_IMAGE); |
| } |
| |
| |
| } |
