1 /******************************************************************************* 2 * Copyright (c) 2007, 2013 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.pde.api.tools.internal.provisional; 15 16 import org.eclipse.core.runtime.IProgressMonitor; 17 import org.eclipse.core.runtime.IStatus; 18 import org.eclipse.pde.api.tools.internal.provisional.descriptors.IElementDescriptor; 19 import org.eclipse.pde.api.tools.internal.provisional.descriptors.IPackageDescriptor; 20 21 /** 22 * Describes the API of an API component. Annotates types as public API, for 23 * private use, etc. 24 * 25 * @noimplement This interface is not to be implemented by clients 26 * 27 * @since 1.0 28 */ 29 public interface IApiDescription { 30 31 /** 32 * Status code indicating an element was not found when attempting to set 33 * its visibility or usage restrictions. 34 */ 35 public static final int ELEMENT_NOT_FOUND = 100; 36 37 /** 38 * Sets the visibility for the specified element in the context of the 39 * specified component and returns a status describing whether the operation 40 * succeeded. 41 * 42 * @param element the element the visibility applies to 43 * @param visibility element visibility. See 44 * {@linkplain VisibilityModifiers} for supported modifiers 45 * 46 * @return status of the operation 47 */ setVisibility(IElementDescriptor element, int visibility)48 public IStatus setVisibility(IElementDescriptor element, int visibility); 49 50 /** 51 * Sets the restrictions for the specified element and returns a status 52 * describing whether the operation succeeded. 53 * 54 * @param element the element the restrictions apply to 55 * @param restrictions the restrictions to place on the element. See 56 * {@linkplain RestrictionModifiers} for supported modifiers 57 * 58 * @return status of the operation 59 */ setRestrictions(IElementDescriptor element, int restrictions)60 public IStatus setRestrictions(IElementDescriptor element, int restrictions); 61 62 /** 63 * Sets the superclass for the specified element and returns a status 64 * describing whether the operation succeeded. 65 * 66 * @param element the element the restrictions apply to 67 * @param superclass the superclass name of the element 68 * 69 * @return status of the operation 70 */ setSuperclass(IElementDescriptor element, String superclass)71 public IStatus setSuperclass(IElementDescriptor element, String superclass); 72 73 /** 74 * Sets the superclass for the specified element and returns a status 75 * describing whether the operation succeeded. 76 * 77 * @param element the element the restrictions apply to 78 * @param superclass the superclass name of the element 79 * 80 * @return status of the operation 81 */ setSuperinterfaces(IElementDescriptor element, String superinterfaces)82 public IStatus setSuperinterfaces(IElementDescriptor element, String superinterfaces); 83 84 /** 85 * Sets the interface flag for the specified element and returns a status 86 * describing whether the operation succeeded. 87 * 88 * @param element the element the restrictions apply to 89 * @param interfaceFlag the interface flag of the element 90 * 91 * @return status of the operation 92 */ setInterface(IElementDescriptor element, boolean interfaceFlag)93 public IStatus setInterface(IElementDescriptor element, boolean interfaceFlag); 94 95 /** 96 * Sets the visibility for the specified element in the context of the 97 * specified component and returns a status describing whether the operation 98 * succeeded. 99 * 100 * @param element the element the visibility applies to 101 * @param visibility element visibility. See 102 * {@linkplain VisibilityModifiers} for supported modifiers 103 * 104 * @return status of the operation 105 */ setAddedProfile(IElementDescriptor element, int addedProfile)106 public IStatus setAddedProfile(IElementDescriptor element, int addedProfile); 107 108 /** 109 * Sets the restrictions for the specified element and returns a status 110 * describing whether the operation succeeded. 111 * 112 * @param element the element the restrictions apply to 113 * @param restrictions the restrictions to place on the element. See 114 * {@linkplain RestrictionModifiers} for supported modifiers 115 * 116 * @return status of the operation 117 */ setRemovedProfile(IElementDescriptor element, int removedProfile)118 public IStatus setRemovedProfile(IElementDescriptor element, int removedProfile); 119 120 /** 121 * Returns annotations for the specified element when referenced from the 122 * specified component. 123 * <p> 124 * If the given element does not appear in the description and none of its 125 * enclosing elements appear in the description, <code>null</code> is 126 * returned. Otherwise the annotations of the first restricted enclosing 127 * member are returned. 128 * </p> 129 * <p> 130 * If there is no component specific API for the specified element, the 131 * general annotations for the element are returned. 132 * </p> 133 * 134 * @param element element to resolve API description for 135 * 136 * @return API annotations or <code>null</code> 137 */ resolveAnnotations(IElementDescriptor element)138 public IApiAnnotations resolveAnnotations(IElementDescriptor element); 139 140 /** 141 * Returns the access level the given element has for the given package. If 142 * there is no special access for the given element <code>null</code> is 143 * returned. 144 * 145 * @param element the element to resolve access for 146 * @param pelement the package being accessed by the given element 147 * 148 * @return API access the given element has to the given package or 149 * <code>null</code> if no special access has been defined 150 */ resolveAccessLevel(IElementDescriptor element, IPackageDescriptor pelement)151 public IApiAccess resolveAccessLevel(IElementDescriptor element, IPackageDescriptor pelement); 152 153 /** 154 * Sets the access level that the given element has to the given package 155 * 156 * @param element the element that has access to the given package 157 * @param pelement the package that the given element will have the given 158 * access to 159 * @param access the desired access level to the given package from the 160 * given element 161 */ setAccessLevel(IElementDescriptor element, IPackageDescriptor pelement, int access)162 public void setAccessLevel(IElementDescriptor element, IPackageDescriptor pelement, int access); 163 164 /** 165 * Traverses this description with the given visitor. 166 * 167 * @param visitor description visitor 168 * @param monitor 169 */ accept(ApiDescriptionVisitor visitor, IProgressMonitor monitor)170 public void accept(ApiDescriptionVisitor visitor, IProgressMonitor monitor); 171 172 /** 173 * Traverses this given element contained in this description, if present. 174 * 175 * @param visitor visitor 176 * @param element element to visit 177 * @param monitor progress monitor or <code>null</code> 178 * @return whether the element was visited - <code>true</code> if present 179 * and <code>false</code> if not present 180 */ accept(ApiDescriptionVisitor visitor, IElementDescriptor element, IProgressMonitor monitor)181 public boolean accept(ApiDescriptionVisitor visitor, IElementDescriptor element, IProgressMonitor monitor); 182 183 } 184