Return-Path: Delivered-To: apmail-db-derby-commits-archive@www.apache.org Received: (qmail 24996 invoked from network); 23 Jan 2009 15:06:21 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 23 Jan 2009 15:06:21 -0000 Received: (qmail 45884 invoked by uid 500); 23 Jan 2009 15:06:21 -0000 Delivered-To: apmail-db-derby-commits-archive@db.apache.org Received: (qmail 45860 invoked by uid 500); 23 Jan 2009 15:06:21 -0000 Mailing-List: contact derby-commits-help@db.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: "Derby Development" List-Id: Delivered-To: mailing list derby-commits@db.apache.org Received: (qmail 45851 invoked by uid 99); 23 Jan 2009 15:06:21 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 23 Jan 2009 07:06:21 -0800 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 23 Jan 2009 15:06:11 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id B18F32388A16; Fri, 23 Jan 2009 07:05:49 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r737043 [1/4] - in /db/derby/code/trunk: ./ java/stubs/felix/ java/stubs/felix/org/ java/stubs/felix/org/osgi/ java/stubs/felix/org/osgi/framework/ tools/ant/properties/ tools/ide/netbeans/6.0/nbproject/ tools/java/ Date: Fri, 23 Jan 2009 15:05:48 -0000 To: derby-commits@db.apache.org From: rhillegas@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090123150549.B18F32388A16@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: rhillegas Date: Fri Jan 23 07:05:47 2009 New Revision: 737043 URL: http://svn.apache.org/viewvc?rev=737043&view=rev Log: DERBY-4024: Replace Felix jar with Felix sources to move us closer to being able to bundle Derby with Debian-lineage linux distributions like Ubuntu. Added: db/derby/code/trunk/java/stubs/felix/ db/derby/code/trunk/java/stubs/felix/org/ db/derby/code/trunk/java/stubs/felix/org/osgi/ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AdminPermission.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AllServiceListener.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Bundle.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleActivator.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleContext.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleEvent.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleException.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleListener.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundlePermission.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Configurable.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Constants.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Filter.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/FrameworkEvent.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/FrameworkListener.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/FrameworkUtil.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/InvalidSyntaxException.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/PackagePermission.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/ServiceEvent.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/ServiceFactory.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/ServiceListener.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/ServicePermission.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/ServiceReference.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/ServiceRegistration.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/SynchronousBundleListener.java (with props) db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Version.java (with props) Removed: db/derby/code/trunk/tools/java/felix.jar Modified: db/derby/code/trunk/NOTICE db/derby/code/trunk/build.xml db/derby/code/trunk/tools/ant/properties/dirs.properties db/derby/code/trunk/tools/ant/properties/extrapath.properties db/derby/code/trunk/tools/ide/netbeans/6.0/nbproject/project.xml Modified: db/derby/code/trunk/NOTICE URL: http://svn.apache.org/viewvc/db/derby/code/trunk/NOTICE?rev=737043&r1=737042&r2=737043&view=diff ============================================================================== --- db/derby/code/trunk/NOTICE (original) +++ db/derby/code/trunk/NOTICE Fri Jan 23 07:05:47 2009 @@ -46,6 +46,42 @@ ========================================================================= +The Derby build relies on source files supplied by the Apache Felix +project. The following notice covers the Felix files: + + Apache Felix Main + Copyright 2008 The Apache Software Foundation + + + I. Included Software + + This product includes software developed at + The Apache Software Foundation (http://www.apache.org/). + Licensed under the Apache License 2.0. + + This product includes software developed at + The OSGi Alliance (http://www.osgi.org/). + Copyright (c) OSGi Alliance (2000, 2007). + Licensed under the Apache License 2.0. + + This product includes software from http://kxml.sourceforge.net. + Copyright (c) 2002,2003, Stefan Haustein, Oberhausen, Rhld., Germany. + Licensed under BSD License. + + II. Used Software + + This product uses software developed at + The OSGi Alliance (http://www.osgi.org/). + Copyright (c) OSGi Alliance (2000, 2007). + Licensed under the Apache License 2.0. + + + III. License Summary + - Apache License 2.0 + - BSD License + +========================================================================= + The Derby build relies on jar files supplied by the Apache Xalan project. The following notice covers the Xalan jar files: Modified: db/derby/code/trunk/build.xml URL: http://svn.apache.org/viewvc/db/derby/code/trunk/build.xml?rev=737043&r1=737042&r2=737043&view=diff ============================================================================== --- db/derby/code/trunk/build.xml (original) +++ db/derby/code/trunk/build.xml Fri Jan 23 07:05:47 2009 @@ -31,7 +31,7 @@ - + @@ -701,6 +701,33 @@ + + + + + + + + + + + + + + + Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AdminPermission.java URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AdminPermission.java?rev=737043&view=auto ============================================================================== --- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AdminPermission.java (added) +++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AdminPermission.java Fri Jan 23 07:05:47 2009 @@ -0,0 +1,406 @@ +/* + * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/AdminPermission.java,v 1.34 2007/02/21 16:49:05 hargrave Exp $ + * + * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved. + * + * Licensed 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.osgi.framework; + +import java.lang.reflect.Constructor; +import java.lang.reflect.InvocationTargetException; +import java.security.*; + +/** + * A bundle's authority to perform specific privileged administrative operations + * on or to get sensitive information about a bundle. The actions for this + * permission are: + * + * 
+ *   Action               Methods
+ *   class                Bundle.loadClass
+ *   execute              Bundle.start
+ *                        Bundle.stop
+ *                        StartLevel.setBundleStartLevel
+ *   extensionLifecycle   BundleContext.installBundle for extension bundles
+ *                        Bundle.update for extension bundles
+ *                        Bundle.uninstall for extension bundles
+ *   lifecycle            BundleContext.installBundle
+ *                        Bundle.update
+ *                        Bundle.uninstall
+ *   listener             BundleContext.addBundleListener for SynchronousBundleListener
+ *                        BundleContext.removeBundleListener for SynchronousBundleListener
+ *   metadata             Bundle.getHeaders
+ *                        Bundle.getLocation
+ *   resolve              PackageAdmin.refreshPackages
+ *                        PackageAdmin.resolveBundles
+ *   resource             Bundle.getResource
+ *                        Bundle.getResources
+ *                        Bundle.getEntry
+ *                        Bundle.getEntryPaths
+ *                        Bundle.findEntries
+ *                        Bundle resource/entry URL creation
+ *   startlevel           StartLevel.setStartLevel
+ *                        StartLevel.setInitialBundleStartLevel 
+ *   context              Bundle.getBundleContext                     
+ *                        
+ *
+ * + *

+ * The special action "*" will represent all actions. + *

+ * The name of this permission is a filter expression. The filter gives access + * to the following parameters: + *

    + *
  • signer - A Distinguished Name chain used to sign a bundle. Wildcards in + * a DN are not matched according to the filter string rules, but according to + * the rules defined for a DN chain.
    • + *
  • location - The location of a bundle.
    • + *
  • id - The bundle ID of the designated bundle.
    • + *
  • name - The symbolic name of a bundle.
    • + *
+ * + * @ThreadSafe + * @version $Revision: 1.34 $ + */ + +public final class AdminPermission extends BasicPermission { + static final long serialVersionUID = 307051004521261705L; + + /** + * The action string class (Value is "class"). + * @since 1.3 + */ + public final static String CLASS = "class"; + /** + * The action string execute (Value is "execute"). + * @since 1.3 + */ + public final static String EXECUTE = "execute"; + /** + * The action string extensionLifecycle (Value is + * "extensionLifecycle"). + * @since 1.3 + */ + public final static String EXTENSIONLIFECYCLE = "extensionLifecycle"; + /** + * The action string lifecycle (Value is "lifecycle"). + * @since 1.3 + */ + public final static String LIFECYCLE = "lifecycle"; + /** + * The action string listener (Value is "listener"). + * @since 1.3 + */ + public final static String LISTENER = "listener"; + /** + * The action string metadata (Value is "metadata"). + * @since 1.3 + */ + public final static String METADATA = "metadata"; + /** + * The action string resolve (Value is "resolve"). + * @since 1.3 + */ + public final static String RESOLVE = "resolve"; + /** + * The action string resource (Value is "resource"). + * @since 1.3 + */ + public final static String RESOURCE = "resource"; + /** + * The action string startlevel (Value is "startlevel"). + * @since 1.3 + */ + public final static String STARTLEVEL = "startlevel"; + + /** + * The action string context (Value is "context"). + * @since 1.4 + */ + public final static String CONTEXT = "context"; + + /* + * NOTE: A framework implementor may also choose to replace this class in + * their distribution with a class that directly interfaces with the + * framework implementation. This replacement class MUST NOT + * alter the public/protected signature of this class. + */ + + /* + * This class will load the AdminPermission class in the package named by + * the org.osgi.vendor.framework package. For each instance of this class, + * an instance of the vendor AdminPermission class will be created and this + * class will delegate method calls to the vendor AdminPermission instance. + */ + + private static class ImplHolder implements PrivilegedAction { + private static final String packageProperty = "org.osgi.vendor.framework"; + static final Constructor initStringString; + static final Constructor initBundleString; + static { + Constructor[] constructors = (Constructor[]) AccessController.doPrivileged(new ImplHolder()); + + initStringString = constructors[0]; + initBundleString = constructors[1]; + } + + private ImplHolder() { + } + + public Object run() { + String packageName = System + .getProperty(packageProperty); + if (packageName == null) { + throw new NoClassDefFoundError(packageProperty + + " property not set"); + } + + Class delegateClass; + try { + delegateClass = Class.forName(packageName + + ".AdminPermission"); + } + catch (ClassNotFoundException e) { + throw new NoClassDefFoundError(e.toString()); + } + + Constructor[] result = new Constructor[2]; + try { + result[0] = delegateClass + .getConstructor(new Class[] {String.class, + String.class }); + result[1] = delegateClass + .getConstructor(new Class[] {Bundle.class, + String.class }); + } + catch (NoSuchMethodException e) { + throw new NoSuchMethodError(e.toString()); + } + + return result; + } + } + + /* + * This is the delegate permission created by the constructor. + */ + private final Permission delegate; + + /** + * Creates a new AdminPermission object that matches all + * bundles and has all actions. Equivalent to AdminPermission("*","*"); + */ + public AdminPermission() { + this("*", "*"); //$NON-NLS-1$ + } + + /** + * Create a new AdminPermission. + * + * This constructor must only be used to create a permission that is going + * to be checked. + *

+ * Examples: + * + * 

+	 * (signer=\*,o=ACME,c=US)   
+	 * (&(signer=\*,o=ACME,c=US)(name=com.acme.*)(location=http://www.acme.com/bundles/*))
+	 * (id>=1)
+	 *
+ * + *

+ * When a signer key is used within the filter expression the signer value + * must escape the special filter chars ('*', '(', ')'). + *

+ * Null arguments are equivalent to "*". + * + * @param filter A filter expression that can use signer, location, id, and + * name keys. A value of "*" or null matches + * all bundle. + * @param actions class, execute, + * extensionLifecycle, lifecycle, + * listener, metadata, + * resolve, resource, + * startlevel or context. A value of "*" or null + * indicates all actions + */ + public AdminPermission(String filter, String actions) { + // arguments will be null if called from a PermissionInfo defined with + // no args + super(filter == null ? "*" : filter); + try { + try { + delegate = (Permission) ImplHolder.initStringString + .newInstance(new Object[] {filter, actions}); + } + catch (InvocationTargetException e) { + throw e.getTargetException(); + } + } + catch (Error e) { + throw e; + } + catch (RuntimeException e) { + throw e; + } + catch (Throwable e) { + throw new RuntimeException(e.toString()); + } + } + + /** + * Creates a new AdminPermission object to be used by the + * code that must check a Permission object. + * + * @param bundle A bundle + * @param actions class, execute, + * extensionLifecycle, lifecycle, + * listener, metadata, + * resolve, resource, + * startlevel, context. + * @since 1.3 + */ + public AdminPermission(Bundle bundle, String actions) { + super(createName(bundle)); + try { + try { + delegate = (Permission) ImplHolder.initBundleString + .newInstance(new Object[] {bundle, actions}); + } + catch (InvocationTargetException e) { + throw e.getTargetException(); + } + } + catch (Error e) { + throw e; + } + catch (RuntimeException e) { + throw e; + } + catch (Throwable e) { + throw new RuntimeException(e.toString()); + } + } + + /** + * Create a permission name from a Bundle + * + * @param bundle Bundle to use to create permission name. + * @return permission name. + */ + private static String createName(Bundle bundle) { + StringBuffer sb = new StringBuffer(); + sb.append("(id="); + sb.append(bundle.getBundleId()); + sb.append(")"); + return sb.toString(); + } + + /** + * Determines the equality of two AdminPermission objects. + * + * @param obj The object being compared for equality with this object. + * @return true if obj is equivalent to this + * AdminPermission; false otherwise. + */ + public boolean equals(Object obj) { + if (obj == this) { + return true; + } + + if (!(obj instanceof AdminPermission)) { + return false; + } + + AdminPermission p = (AdminPermission) obj; + + return delegate.equals(p.delegate); + } + + /** + * Returns the hash code value for this object. + * + * @return Hash code value for this object. + */ + public int hashCode() { + return delegate.hashCode(); + } + + /** + * Returns the canonical string representation of the + * AdminPermission actions. + * + *

+ * Always returns present AdminPermission actions in the + * following order: class, execute, + * extensionLifecycle, lifecycle, + * listener, metadata, resolve, + * resource, startlevel, context. + * + * @return Canonical string representation of the + * AdminPermission actions. + */ + public String getActions() { + return delegate.getActions(); + } + + /** + * Determines if the specified permission is implied by this object. This + * method throws an exception if the specified permission was not + * constructed with a bundle. + * + *

+ * This method returns true if the specified permission is an + * AdminPermission AND + *

    + *
  • this object's filter matches the specified permission's bundle ID, + * bundle symbolic name, bundle location and bundle signer distinguished + * name chain OR
    • + *
  • this object's filter is "*"
    • + *
+ * AND this object's actions include all of the specified permission's + * actions. + *

+ * Special case: if the specified permission was constructed with "*" + * filter, then this method returns true if this object's + * filter is "*" and this object's actions include all of the specified + * permission's actions + * + * @param p The permission to interrogate. + * + * @return true if the specified permission is implied by + * this object; false otherwise. + * @throws RuntimeException if specified permission was not constructed with + * a bundle or "*" + */ + public boolean implies(Permission p) { + if (!(p instanceof AdminPermission)) { + return false; + } + + AdminPermission pp = (AdminPermission) p; + return delegate.implies(pp.delegate); + } + + /** + * Returns a new PermissionCollection object suitable for + * storing AdminPermissions. + * + * @return A new PermissionCollection object. + */ + public PermissionCollection newPermissionCollection() { + return delegate.newPermissionCollection(); + } +} Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AdminPermission.java ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AllServiceListener.java URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AllServiceListener.java?rev=737043&view=auto ============================================================================== --- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AllServiceListener.java (added) +++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AllServiceListener.java Fri Jan 23 07:05:47 2009 @@ -0,0 +1,65 @@ +/* + * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/AllServiceListener.java,v 1.10 2007/02/20 00:16:30 hargrave Exp $ + * + * Copyright (c) OSGi Alliance (2005, 2007). All Rights Reserved. + * + * Licensed 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.osgi.framework; + +/** + * A ServiceEvent listener that does not filter based upon + * package wiring. AllServiceListener is a listener interface + * that may be implemented by a bundle developer. When a + * ServiceEvent is fired, it is synchronously delivered to an + * AllServiceListener. The Framework may deliver + * ServiceEvent objects to an AllServiceListener + * out of order and may concurrently call and/or reenter an + * AllServiceListener. + *

+ * An AllServiceListener object is registered with the Framework + * using the BundleContext.addServiceListener method. + * AllServiceListener objects are called with a + * ServiceEvent object when a service is registered, modified, or + * is in the process of unregistering. + * + *

+ * ServiceEvent object delivery to + * AllServiceListener objects is filtered by the filter specified + * when the listener was registered. If the Java Runtime Environment supports + * permissions, then additional filtering is done. ServiceEvent + * objects are only delivered to the listener if the bundle which defines the + * listener object's class has the appropriate ServicePermission + * to get the service using at least one of the named classes under which the + * service was registered. + * + *

+ * Unlike normal ServiceListener objects, + * AllServiceListener objects receive all + * ServiceEvent objects regardless of whether the package source + * of the listening bundle is equal to the package source of the bundle that + * registered the service. This means that the listener may not be able to cast + * the service object to any of its corresponding service interfaces if the + * service object is retrieved. + * + * @see ServiceEvent + * @see ServicePermission + * @ThreadSafe + * @since 1.3 + * @version $Revision: 1.10 $ + */ + +public interface AllServiceListener extends ServiceListener { + // This is a marker interface +} Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/AllServiceListener.java ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Bundle.java URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Bundle.java?rev=737043&view=auto ============================================================================== --- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Bundle.java (added) +++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Bundle.java Fri Jan 23 07:05:47 2009 @@ -0,0 +1,1120 @@ +/* + * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/Bundle.java,v 1.54 2007/02/21 16:49:05 hargrave Exp $ + * + * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved. + * + * Licensed 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.osgi.framework; + +import java.io.IOException; +import java.io.InputStream; +import java.net.URL; +import java.util.Dictionary; +import java.util.Enumeration; + +/** + * An installed bundle in the Framework. + * + *

+ * A Bundle object is the access point to define the lifecycle of + * an installed bundle. Each bundle installed in the OSGi environment must have + * an associated Bundle object. + * + *

+ * A bundle must have a unique identity, a long, chosen by the + * Framework. This identity must not change during the lifecycle of a bundle, + * even when the bundle is updated. Uninstalling and then reinstalling the + * bundle must create a new unique identity. + * + *

+ * A bundle can be in one of six states: + *

    + *
  • {@link #UNINSTALLED} + *
  • {@link #INSTALLED} + *
  • {@link #RESOLVED} + *
  • {@link #STARTING} + *
  • {@link #STOPPING} + *
  • {@link #ACTIVE} + *
+ *

+ * Values assigned to these states have no specified ordering; they represent + * bit values that may be ORed together to determine if a bundle is in one of + * the valid states. + * + *

+ * A bundle should only execute code when its state is one of + * STARTING,ACTIVE, or STOPPING. + * An UNINSTALLED bundle can not be set to another state; it is a + * zombie and can only be reached because references are kept somewhere. + * + *

+ * The Framework is the only entity that is allowed to create + * Bundle objects, and these objects are only valid within the + * Framework that created them. + * + * @ThreadSafe + * @version $Revision: 1.54 $ + */ +public interface Bundle { + /** + * The bundle is uninstalled and may not be used. + * + *

+ * The UNINSTALLED state is only visible after a bundle is + * uninstalled; the bundle is in an unusable state but references to the + * Bundle object may still be available and used for + * introspection. + *

+ * The value of UNINSTALLED is 0x00000001. + */ + public static final int UNINSTALLED = 0x00000001; + + /** + * The bundle is installed but not yet resolved. + * + *

+ * A bundle is in the INSTALLED state when it has been + * installed in the Framework but is not or cannot be resolved. + *

+ * This state is visible if the bundle's code dependencies are not resolved. + * The Framework may attempt to resolve an INSTALLED bundle's + * code dependencies and move the bundle to the RESOLVED + * state. + *

+ * The value of INSTALLED is 0x00000002. + */ + public static final int INSTALLED = 0x00000002; + + /** + * The bundle is resolved and is able to be started. + * + *

+ * A bundle is in the RESOLVED state when the Framework has + * successfully resolved the bundle's code dependencies. These dependencies + * include: + *

    + *
  • The bundle's class path from its {@link Constants#BUNDLE_CLASSPATH} + * Manifest header. + *
  • The bundle's package dependencies from its + * {@link Constants#EXPORT_PACKAGE} and {@link Constants#IMPORT_PACKAGE} + * Manifest headers. + *
  • The bundle's required bundle dependencies from its + * {@link Constants#REQUIRE_BUNDLE} Manifest header. + *
  • A fragment bundle's host dependency from its + * {@link Constants#FRAGMENT_HOST} Manifest header. + *
+ *

+ * Note that the bundle is not active yet. A bundle must be put in the + * RESOLVED state before it can be started. The Framework may + * attempt to resolve a bundle at any time. + *

+ * The value of RESOLVED is 0x00000004. + */ + public static final int RESOLVED = 0x00000004; + + /** + * The bundle is in the process of starting. + * + *

+ * A bundle is in the STARTING state when its + * {@link #start(int) start} method is active. A bundle must be in this + * state when the bundle's {@link BundleActivator#start} is called. If the + * BundleActivator.start method completes without exception, + * then the bundle has successfully started and must move to the + * ACTIVE state. + *

+ * If the bundle has a + * {@link Constants#ACTIVATION_LAZY lazy activation policy}, then the + * bundle may remain in this state for some time until the activation is + * triggered. + *

+ * The value of STARTING is 0x00000008. + */ + public static final int STARTING = 0x00000008; + + /** + * The bundle is in the process of stopping. + * + *

+ * A bundle is in the STOPPING state when its + * {@link #stop(int) stop} method is active. A bundle must be in this state + * when the bundle's {@link BundleActivator#stop} method is called. When the + * BundleActivator.stop method completes the bundle is + * stopped and must move to the RESOLVED state. + *

+ * The value of STOPPING is 0x00000010. + */ + public static final int STOPPING = 0x00000010; + + /** + * The bundle is now running. + * + *

+ * A bundle is in the ACTIVE state when it has been + * successfully started and activated. + *

+ * The value of ACTIVE is 0x00000020. + */ + public static final int ACTIVE = 0x00000020; + + /** + * The bundle start operation is transient and the persistent autostart + * setting of the bundle is not modified. + * + *

+ * This bit may be set when calling {@link #start(int)} to notify the + * framework that the autostart setting of the bundle must not be modified. + * If this bit is not set, then the autostart setting of the bundle is + * modified. + * + * @since 1.4 + * @see #start(int) + */ + public static final int START_TRANSIENT = 0x00000001; + + /** + * The bundle start operation must activate the bundle according to the + * bundle's declared + * {@link Constants#BUNDLE_ACTIVATIONPOLICY activation policy}. + * + *

+ * This bit may be set when calling {@link #start(int)} to notify the + * framework that the bundle must be activated using the bundle's declared + * activation policy. + * + * @since 1.4 + * @see Constants#BUNDLE_ACTIVATIONPOLICY + * @see #start(int) + */ + public static final int START_ACTIVATION_POLICY = 0x00000002; + + /** + * The bundle stop is transient and the persistent autostart setting of the + * bundle is not modified. + * + *

+ * This bit may be set when calling {@link #stop(int)} to notify the + * framework that the autostart setting of the bundle must not be modified. + * If this bit is not set, then the autostart setting of the bundle is + * modified. + * + * @since 1.4 + * @see #stop(int) + */ + public static final int STOP_TRANSIENT = 0x00000001; + + /** + * Returns this bundle's current state. + * + *

+ * A bundle can be in only one state at any time. + * + * @return An element of UNINSTALLED,INSTALLED, + * RESOLVED,STARTING, + * STOPPING,ACTIVE. + */ + public int getState(); + + /** + * Starts this bundle. + * + *

+ * If this bundle's state is UNINSTALLED then an + * IllegalStateException is thrown. + *

+ * If the Framework implements the optional Start Level service and the + * current start level is less than this bundle's start level: + *

    + *
  • If the {@link #START_TRANSIENT} option is set, then a + * BundleException is thrown indicating this bundle cannot be + * started due to the Framework's current start level. + * + *
  • Otherwise, the Framework must set this bundle's persistent autostart + * setting to Started with declared activation if the + * {@link #START_ACTIVATION_POLICY} option is set or + * Started with eager activation if not set. + *
+ *

+ * When the Framework's current start level becomes equal to or more than + * this bundle's start level, this bundle will be started. + *

+ * Otherwise, the following steps are required to start this bundle: + *

    + *
  1. If this bundle is in the process of being activated or deactivated + * then this method must wait for activation or deactivation to complete + * before continuing. If this does not occur in a reasonable time, a + * BundleException is thrown to indicate this bundle was + * unable to be started. + * + *
  2. If this bundle's state is ACTIVE then this method + * returns immediately. + * + *
  3. If the {@link #START_TRANSIENT} option is not set then set this + * bundle's autostart setting to Started with declared activation + * if the {@link #START_ACTIVATION_POLICY} option is set or + * Started with eager activation if not set. When the Framework + * is restarted and this bundle's autostart setting is not Stopped, + * this bundle must be automatically started. + * + *
  4. If this bundle's state is not RESOLVED, an attempt + * is made to resolve this bundle. If the Framework cannot resolve this + * bundle, a BundleException is thrown. + * + *
  5. If the {@link #START_ACTIVATION_POLICY} option is set and this + * bundle's declared activation policy is + * {@link Constants#ACTIVATION_LAZY lazy} then: + *
      + *
    • If this bundle's state is STARTING then this method + * returns immediately. + *
    • This bundle's state is set to STARTING. + *
    • A bundle event of type {@link BundleEvent#LAZY_ACTIVATION} is fired. + *
    • This method returns immediately and the remaining steps will be + * followed when this bundle's activation is later triggered. + *
    + * + *
  6. This bundle's state is set to STARTING. + * + *
  7. A bundle event of type {@link BundleEvent#STARTING} is fired. + * + *
  8. The {@link BundleActivator#start} method of this bundle's + * BundleActivator, if one is specified, is called. If the + * BundleActivator is invalid or throws an exception then: + *
      + *
    • This bundle's state is set to STOPPING. + *
    • A bundle event of type {@link BundleEvent#STOPPING} is fired. + *
    • Any services registered by this bundle must be unregistered. + *
    • Any services used by this bundle must be released. + *
    • Any listeners registered by this bundle must be removed. + *
    • This bundle's state is set to RESOLVED. + *
    • A bundle event of type {@link BundleEvent#STOPPED} is fired. + *
    • A BundleException is then thrown. + *
    + * + *
  9. If this bundle's state is UNINSTALLED, because this + * bundle was uninstalled while the BundleActivator.start + * method was running, a BundleException is thrown. + * + *
  10. This bundle's state is set to ACTIVE. + * + *
  11. A bundle event of type {@link BundleEvent#STARTED} is fired. + *
+ * + * Preconditions + *
    + *
  • getState() in {INSTALLED, + * RESOLVED} or {INSTALLED, + * RESOLVED, STARTING} if this bundle has a + * lazy activation policy. + *
+ * Postconditions, no exceptions thrown + *
    + *
  • Bundle autostart setting is modified unless the + * {@link #START_TRANSIENT} option was set. + *
  • getState() in {ACTIVE} unless the + * lazy activation policy was used. + *
  • BundleActivator.start() has been called and did not + * throw an exception unless the lazy activation policy was used. + *
+ * Postconditions, when an exception is thrown + *
    + *
  • Depending on when the exception occurred, bundle autostart setting + * is modified unless the {@link #START_TRANSIENT} option was set. + *
  • getState() not in {STARTING, + * ACTIVE}. + *
+ * + * @param options The options for starting this bundle. See + * {@link #START_TRANSIENT} and {@link #START_ACTIVATION_POLICY}. + * The Framework must ignore unrecognized options. + * @throws BundleException If this bundle could not be started. This could + * be because a code dependency could not be resolved or the + * specified BundleActivator could not be loaded or + * threw an exception or this bundle is a fragment. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled or this bundle tries to change its own state. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,EXECUTE], and + * the Java Runtime Environment supports permissions. + * @since 1.4 + */ + public void start(int options) throws BundleException; + + /** + * Starts this bundle with no options. + * + *

+ * This method calls start(0). + * + * @throws BundleException If this bundle could not be started. This could + * be because a code dependency could not be resolved or the + * specified BundleActivator could not be loaded or + * threw an exception or this bundle is a fragment. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled or this bundle tries to change its own state. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,EXECUTE], and + * the Java Runtime Environment supports permissions. + * @see #start(int) + */ + public void start() throws BundleException; + + /** + * Stops this bundle. + * + *

+ * The following steps are required to stop a bundle: + *

    + *
  1. If this bundle's state is UNINSTALLED then an + * IllegalStateException is thrown. + * + *
  2. If this bundle is in the process of being activated or deactivated + * then this method must wait for activation or deactivation to complete + * before continuing. If this does not occur in a reasonable time, a + * BundleException is thrown to indicate this bundle was + * unable to be stopped. + *
  3. If the {@link #STOP_TRANSIENT} option is not set then then set this + * bundle's persistent autostart setting to to Stopped. When the + * Framework is restarted and this bundle's autostart setting is + * Stopped, this bundle must not be automatically started. + * + *
  4. If this bundle's state is not ACTIVE then this method + * returns immediately. + * + *
  5. This bundle's state is set to STOPPING. + * + *
  6. A bundle event of type {@link BundleEvent#STOPPING} is fired. + * + *
  7. The {@link BundleActivator#stop} method of this bundle's + * BundleActivator, if one is specified, is called. If that + * method throws an exception, this method must continue to stop this + * bundle. A BundleException must be thrown after completion + * of the remaining steps. + * + *
  8. Any services registered by this bundle must be unregistered. + *
  9. Any services used by this bundle must be released. + *
  10. Any listeners registered by this bundle must be removed. + * + *
  11. If this bundle's state is UNINSTALLED, because this + * bundle was uninstalled while the BundleActivator.stop + * method was running, a BundleException must be thrown. + * + *
  12. This bundle's state is set to RESOLVED. + * + *
  13. A bundle event of type {@link BundleEvent#STOPPED} is fired. + *
+ * + * Preconditions + *
    + *
  • getState() in {ACTIVE}. + *
+ * Postconditions, no exceptions thrown + *
    + *
  • Bundle autostart setting is modified unless the + * {@link #STOP_TRANSIENT} option was set. + *
  • getState() not in {ACTIVE, + * STOPPING}. + *
  • BundleActivator.stop has been called and did not + * throw an exception. + *
+ * Postconditions, when an exception is thrown + *
    + *
  • Bundle autostart setting is modified unless the + * {@link #STOP_TRANSIENT} option was set. + *
+ * + * @param options The options for stoping this bundle. See + * {@link #STOP_TRANSIENT}. The Framework must ignore unrecognized + * options. + * @throws BundleException If this bundle's BundleActivator + * threw an exception or this bundle is a fragment. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled or this bundle tries to change its own state. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,EXECUTE], and + * the Java Runtime Environment supports permissions. + * @since 1.4 + */ + public void stop(int options) throws BundleException; + + /** + * Stops this bundle with no options. + * + *

+ * This method calls stop(0). + * + * @throws BundleException If this bundle's BundleActivator + * threw an exception or this bundle is a fragment. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled or this bundle tries to change its own state. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,EXECUTE], and + * the Java Runtime Environment supports permissions. + * @see #start(int) + */ + public void stop() throws BundleException; + + /** + * Updates this bundle. + * + *

+ * If this bundle's state is ACTIVE, it must be stopped + * before the update and started after the update successfully completes. + * + *

+ * If this bundle has exported any packages, these packages must not be + * updated. Instead, the previous package version must remain exported until + * the PackageAdmin.refreshPackages method has been has been + * called or the Framework is relaunched. + * + *

+ * The following steps are required to update a bundle: + *

    + *
  1. If this bundle's state is UNINSTALLED then an + * IllegalStateException is thrown. + * + *
  2. If this bundle's state is ACTIVE, + * STARTING or STOPPING, this bundle is + * stopped as described in the Bundle.stop method. If + * Bundle.stop throws an exception, the exception is rethrown + * terminating the update. + * + *
  3. The download location of the new version of this bundle is + * determined from either this bundle's + * {@link Constants#BUNDLE_UPDATELOCATION} Manifest header (if available) or + * this bundle's original location. + * + *
  4. The location is interpreted in an implementation dependent manner, + * typically as a URL, and the new version of this bundle is obtained from + * this location. + * + *
  5. The new version of this bundle is installed. If the Framework is + * unable to install the new version of this bundle, the original version of + * this bundle must be restored and a BundleException must be + * thrown after completion of the remaining steps. + * + *
  6. If this bundle has declared an Bundle-RequiredExecutionEnvironment + * header, then the listed execution environments must be verified against + * the installed execution environments. If they do not all match, the + * original version of this bundle must be restored and a + * BundleException must be thrown after completion of the + * remaining steps. + * + *
  7. This bundle's state is set to INSTALLED. + * + *
  8. If the new version of this bundle was successfully installed, a + * bundle event of type {@link BundleEvent#UPDATED} is fired. + * + *
  9. If this bundle's state was originally ACTIVE, the + * updated bundle is started as described in the Bundle.start + * method. If Bundle.start throws an exception, a Framework + * event of type {@link FrameworkEvent#ERROR} is fired containing the + * exception. + *
+ * + * Preconditions + *
    + *
  • getState() not in {UNINSTALLED}. + *
+ * Postconditions, no exceptions thrown + *
    + *
  • getState() in {INSTALLED, + * RESOLVED,ACTIVE}. + *
  • This bundle has been updated. + *
+ * Postconditions, when an exception is thrown + *
    + *
  • getState() in {INSTALLED, + * RESOLVED,ACTIVE}. + *
  • Original bundle is still used; no update occurred. + *
+ * + * @throws BundleException If the update fails. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled or this bundle tries to change its own state. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,LIFECYCLE] for + * both the current bundle and the updated bundle, and the Java + * Runtime Environment supports permissions. + * @see #stop() + * @see #start() + */ + public void update() throws BundleException; + + /** + * Updates this bundle from an InputStream. + * + *

+ * This method performs all the steps listed in Bundle.update(), + * except the new version of this bundle must be read from the supplied + * InputStream, rather than a URL. + *

+ * This method must always close the InputStream when it is + * done, even if an exception is thrown. + * + * @param in The InputStream from which to read the new + * bundle. + * @throws BundleException If the provided stream cannot be read or the + * update fails. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled or this bundle tries to change its own state. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,LIFECYCLE] for + * both the current bundle and the updated bundle, and the Java + * Runtime Environment supports permissions. + * @see #update() + */ + public void update(InputStream in) throws BundleException; + + /** + * Uninstalls this bundle. + * + *

+ * This method causes the Framework to notify other bundles that this bundle + * is being uninstalled, and then puts this bundle into the + * UNINSTALLED state. The Framework must remove any resources + * related to this bundle that it is able to remove. + * + *

+ * If this bundle has exported any packages, the Framework must continue to + * make these packages available to their importing bundles until the + * PackageAdmin.refreshPackages method has been called or the + * Framework is relaunched. + * + *

+ * The following steps are required to uninstall a bundle: + *

    + *
  1. If this bundle's state is UNINSTALLED then an + * IllegalStateException is thrown. + * + *
  2. If this bundle's state is ACTIVE, + * STARTING or STOPPING, this bundle is + * stopped as described in the Bundle.stop method. If + * Bundle.stop throws an exception, a Framework event of type + * {@link FrameworkEvent#ERROR} is fired containing the exception. + * + *
  3. This bundle's state is set to UNINSTALLED. + * + *
  4. A bundle event of type {@link BundleEvent#UNINSTALLED} is fired. + * + *
  5. This bundle and any persistent storage area provided for this bundle + * by the Framework are removed. + *
+ * + * Preconditions + *
    + *
  • getState() not in {UNINSTALLED}. + *
+ * Postconditions, no exceptions thrown + *
    + *
  • getState() in {UNINSTALLED}. + *
  • This bundle has been uninstalled. + *
+ * Postconditions, when an exception is thrown + *
    + *
  • getState() not in {UNINSTALLED}. + *
  • This Bundle has not been uninstalled. + *
+ * + * @throws BundleException If the uninstall failed. This can occur if + * another thread is attempting to change this bundle's state and + * does not complete in a timely manner. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled or this bundle tries to change its own state. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,LIFECYCLE], and + * the Java Runtime Environment supports permissions. + * @see #stop() + */ + public void uninstall() throws BundleException; + + /** + * Returns this bundle's Manifest headers and values. This method returns + * all the Manifest headers and values from the main section of this + * bundle's Manifest file; that is, all lines prior to the first blank line. + * + *

+ * Manifest header names are case-insensitive. The methods of the returned + * Dictionary object must operate on header names in a + * case-insensitive manner. + * + * If a Manifest header value starts with "%", it must be + * localized according to the default locale. + * + *

+ * For example, the following Manifest headers and values are included if + * they are present in the Manifest file: + * + * 

+	 *     Bundle-Name
+	 *     Bundle-Vendor
+	 *     Bundle-Version
+	 *     Bundle-Description
+	 *     Bundle-DocURL
+	 *     Bundle-ContactAddress
+	 *
+ * + *

+ * This method must continue to return Manifest header information while + * this bundle is in the UNINSTALLED state. + * + * @return A Dictionary object containing this bundle's + * Manifest headers and values. + * + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,METADATA], and + * the Java Runtime Environment supports permissions. + * + * @see Constants#BUNDLE_LOCALIZATION + */ + public Dictionary getHeaders(); + + /** + * Returns this bundle's unique identifier. This bundle is assigned a unique + * identifier by the Framework when it was installed in the OSGi + * environment. + * + *

+ * A bundle's unique identifier has the following attributes: + *

    + *
  • Is unique and persistent. + *
  • Is a long. + *
  • Its value is not reused for another bundle, even after a bundle is + * uninstalled. + *
  • Does not change while a bundle remains installed. + *
  • Does not change when a bundle is updated. + *
+ * + *

+ * This method must continue to return this bundle's unique identifier while + * this bundle is in the UNINSTALLED state. + * + * @return The unique identifier of this bundle. + */ + public long getBundleId(); + + /** + * Returns this bundle's location identifier. + * + *

+ * The location identifier is the location passed to + * BundleContext.installBundle when a bundle is installed. + * The location identifier does not change while this bundle remains + * installed, even if this bundle is updated. + * + *

+ * This method must continue to return this bundle's location identifier + * while this bundle is in the UNINSTALLED state. + * + * @return The string representation of this bundle's location identifier. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,METADATA], and + * the Java Runtime Environment supports permissions. + */ + public String getLocation(); + + /** + * Returns this bundle's ServiceReference list for all + * services it has registered or null if this bundle has no + * registered services. + * + *

+ * If the Java runtime supports permissions, a ServiceReference + * object to a service is included in the returned list only if the caller + * has the ServicePermission to get the service using at + * least one of the named classes the service was registered under. + * + *

+ * The list is valid at the time of the call to this method, however, as the + * Framework is a very dynamic environment, services can be modified or + * unregistered at anytime. + * + * @return An array of ServiceReference objects or + * null. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + * @see ServiceRegistration + * @see ServiceReference + * @see ServicePermission + */ + public ServiceReference[] getRegisteredServices(); + + /** + * Returns this bundle's ServiceReference list for all + * services it is using or returns null if this bundle is not + * using any services. A bundle is considered to be using a service if its + * use count for that service is greater than zero. + * + *

+ * If the Java Runtime Environment supports permissions, a + * ServiceReference object to a service is included in the + * returned list only if the caller has the ServicePermission + * to get the service using at least one of the named classes the service + * was registered under. + *

+ * The list is valid at the time of the call to this method, however, as the + * Framework is a very dynamic environment, services can be modified or + * unregistered at anytime. + * + * @return An array of ServiceReference objects or + * null. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + * @see ServiceReference + * @see ServicePermission + */ + public ServiceReference[] getServicesInUse(); + + /** + * Determines if this bundle has the specified permissions. + * + *

+ * If the Java Runtime Environment does not support permissions, this method + * always returns true. + *

+ * permission is of type Object to avoid + * referencing the java.security.Permission class directly. + * This is to allow the Framework to be implemented in Java environments + * which do not support permissions. + * + *

+ * If the Java Runtime Environment does support permissions, this bundle and + * all its resources including embedded JAR files, belong to the same + * java.security.ProtectionDomain; that is, they must share + * the same set of permissions. + * + * @param permission The permission to verify. + * + * @return true if this bundle has the specified permission + * or the permissions possessed by this bundle imply the specified + * permission; false if this bundle does not have the + * specified permission or permission is not an + * instanceof java.security.Permission. + * + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + */ + public boolean hasPermission(Object permission); + + /** + * Find the specified resource from this bundle. + * + * This bundle's class loader is called to search for the specified + * resource. If this bundle's state is INSTALLED, this + * method must attempt to resolve this bundle before attempting to get the + * specified resource. If this bundle cannot be resolved, then only this + * bundle must be searched for the specified resource. Imported packages + * cannot be searched when this bundle has not been resolved. If this bundle + * is a fragment bundle then null is returned. + * + * @param name The name of the resource. See + * java.lang.ClassLoader.getResource for a description + * of the format of a resource name. + * @return A URL to the named resource, or null if the + * resource could not be found or if this bundle is a fragment + * bundle or if the caller does not have the appropriate + * AdminPermission[this,RESOURCE], and the Java + * Runtime Environment supports permissions. + * + * @since 1.1 + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + * @see #getEntry + * @see #findEntries + */ + public URL getResource(String name); + + /** + * Returns this bundle's Manifest headers and values localized to the + * specified locale. + * + *

+ * This method performs the same function as + * Bundle.getHeaders() except the manifest header values are + * localized to the specified locale. + * + *

+ * If a Manifest header value starts with "%", it must be + * localized according to the specified locale. If a locale is specified and + * cannot be found, then the header values must be returned using the + * default locale. Localizations are searched for in the following order: + * + * 

+	 *   bn + "_" + Ls + "_" + Cs + "_" + Vs
+     *   bn + "_" + Ls + "_" + Cs
+     *   bn + "_" + Ls
+     *   bn + "_" + Ld + "_" + Cd + "_" + Vd
+     *   bn + "_" + Ld + "_" + Cd
+     *   bn + "_" + Ld
+	 *     bn
+	 *
+ * + * Where bn is this bundle's localization basename, + * Ls, Cs and Vs are the + * specified locale (language, country, variant) and Ld, + * Cd and Vd are the default locale (language, + * country, variant). + * + * If null is specified as the locale string, the header + * values must be localized using the default locale. If the empty string + * ("") is specified as the locale string, the header values must + * not be localized and the raw (unlocalized) header values, including any + * leading "%", must be returned. + * + *

+ * This method must continue to return Manifest header information while + * this bundle is in the UNINSTALLED state, however the + * header values must only be available in the raw and default locale + * values. + * + * @param locale The locale name into which the header values are to be + * localized. If the specified locale is null then the + * locale returned by java.util.Locale.getDefault is + * used. If the specified locale is the empty string, this method + * will return the raw (unlocalized) manifest headers including any + * leading "%". + * @return A Dictionary object containing this bundle's + * Manifest headers and values. + * + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,METADATA], and + * the Java Runtime Environment supports permissions. + * + * @see #getHeaders() + * @see Constants#BUNDLE_LOCALIZATION + * @since 1.3 + */ + public Dictionary getHeaders(String locale); + + /** + * Returns the symbolic name of this bundle as specified by its + * Bundle-SymbolicName manifest header. The name must be + * unique, it is recommended to use a reverse domain name naming convention + * like that used for java packages. If this bundle does not have a + * specified symbolic name then null is returned. + * + *

+ * This method must continue to return this bundle's symbolic name while + * this bundle is in the UNINSTALLED state. + * + * @return The symbolic name of this bundle. + * @since 1.3 + */ + public String getSymbolicName(); + + /** + * Loads the specified class using this bundle's classloader. + * + *

+ * If this bundle is a fragment bundle then this method must throw a + * ClassNotFoundException. + * + *

+ * If this bundle's state is INSTALLED, this method must + * attempt to resolve this bundle before attempting to load the class. + * + *

+ * If this bundle cannot be resolved, a Framework event of type + * {@link FrameworkEvent#ERROR} is fired containing a + * BundleException with details of the reason this bundle + * could not be resolved. This method must then throw a + * ClassNotFoundException. + * + *

+ * If this bundle's state is UNINSTALLED, then an + * IllegalStateException is thrown. + * + * @param name The name of the class to load. + * @return The Class object for the requested class. + * @throws java.lang.ClassNotFoundException If no such class can be found or + * if this bundle is a fragment bundle or if the caller does not + * have the appropriate AdminPermission[this,CLASS], + * and the Java Runtime Environment supports permissions. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + * @since 1.3 + */ + public Class loadClass(String name) throws ClassNotFoundException; + + /** + * Find the specified resources from this bundle. + * + * This bundle's class loader is called to search for the specified + * resources. If this bundle's state is INSTALLED, this + * method must attempt to resolve this bundle before attempting to get the + * specified resources. If this bundle cannot be resolved, then only this + * bundle must be searched for the specified resources. Imported packages + * cannot be searched when a bundle has not been resolved. If this bundle is + * a fragment bundle then null is returned. + * + * @param name The name of the resource. See + * java.lang.ClassLoader.getResources for a + * description of the format of a resource name. + * @return An enumeration of URLs to the named resources, or + * null if the resource could not be found or if this + * bundle is a fragment bundle or if the caller does not have the + * appropriate AdminPermission[this,RESOURCE], and + * the Java Runtime Environment supports permissions. + * + * @since 1.3 + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + * @throws java.io.IOException If there is an I/O error. + */ + public Enumeration getResources(String name) throws IOException; + + /** + * Returns an Enumeration of all the paths (String objects) + * to entries within this bundle whose longest sub-path matches the + * specified path. This bundle's classloader is not used to search for + * entries. Only the contents of this bundle are searched. + *

+ * The specified path is always relative to the root of this bundle and may + * begin with a "/". A path value of "/" indicates the + * root of this bundle. + *

+ * Returned paths indicating subdirectory paths end with a "/". + * The returned paths are all relative to the root of this bundle and must + * not begin with "/". + * + * @param path The path name for which to return entry paths. + * @return An Enumeration of the entry paths (String + * objects) or null if no entry could be found or if + * the caller does not have the appropriate + * AdminPermission[this,RESOURCE] and the Java + * Runtime Environment supports permissions. + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + * @since 1.3 + */ + public Enumeration getEntryPaths(String path); + + /** + * Returns a URL to the entry at the specified path in this bundle. This + * bundle's classloader is not used to search for the entry. Only the + * contents of this bundle are searched for the entry. + *

+ * The specified path is always relative to the root of this bundle and may + * begin with "/". A path value of "/" indicates the + * root of this bundle. + * + * @param path The path name of the entry. + * @return A URL to the entry, or null if no entry could be + * found or if the caller does not have the appropriate + * AdminPermission[this,RESOURCE] and the Java + * Runtime Environment supports permissions. + * + * @throws java.lang.IllegalStateException If this bundle has been + * uninstalled. + * @since 1.3 + */ + public URL getEntry(String path); + + /** + * Returns the time when this bundle was last modified. A bundle is + * considered to be modified when it is installed, updated or uninstalled. + * + *

+ * The time value is the number of milliseconds since January 1, 1970, + * 00:00:00 GMT. + * + * @return The time when this bundle was last modified. + * @since 1.3 + */ + public long getLastModified(); + + /** + * Returns entries in this bundle and its attached fragments. This bundle's + * classloader is not used to search for entries. Only the contents of this + * bundle and its attached fragments are searched for the specified entries. + * + * If this bundle's state is INSTALLED, this method must + * attempt to resolve this bundle before attempting to find entries. + * + *

+ * This method is intended to be used to obtain configuration, setup, + * localization and other information from this bundle. This method takes + * into account that the "contents" of this bundle can be extended + * with fragments. This "bundle space" is not a namespace with + * unique members; the same entry name can be present multiple times. This + * method therefore returns an enumeration of URL objects. These URLs can + * come from different JARs but have the same path name. This method can + * either return only entries in the specified path or recurse into + * subdirectories returning entries in the directory tree beginning at the + * specified path. Fragments can be attached after this bundle is resolved, + * possibly changing the set of URLs returned by this method. If this bundle + * is not resolved, only the entries in the JAR file of this bundle are + * returned. + *

+ * Examples: + * + * 

+	 * // List all XML files in the OSGI-INF directory and below
+	 * Enumeration e = b.findEntries("OSGI-INF", "*.xml", true);
+	 * 
+	 * // Find a specific localization file
+	 * Enumeration e = b.findEntries("OSGI-INF/l10n", 
+	 *                               "bundle_nl_DU.properties", 
+	 *                               false);
+	 * if (e.hasMoreElements())
+	 * 	return (URL) e.nextElement();
+	 *
+ * + * @param path The path name in which to look. The path is always relative + * to the root of this bundle and may begin with "/". A + * path value of "/" indicates the root of this bundle. + * @param filePattern The file name pattern for selecting entries in the + * specified path. The pattern is only matched against the last + * element of the entry path and it supports substring matching, as + * specified in the Filter specification, using the wildcard + * character ("*"). If null is specified, this is + * equivalent to "*" and matches all files. + * @param recurse If true, recurse into subdirectories. + * Otherwise only return entries from the specified path. + * @return An enumeration of URL objects for each matching entry, or + * null if an entry could not be found or if the + * caller does not have the appropriate + * AdminPermission[this,RESOURCE], and the Java + * Runtime Environment supports permissions. The URLs are sorted + * such that entries from this bundle are returned first followed by + * the entries from attached fragments in ascending bundle id order. + * If this bundle is a fragment, then only matching entries in this + * fragment are returned. + * @since 1.3 + */ + public Enumeration findEntries(String path, String filePattern, + boolean recurse); + + /** + * Returns this bundle's {@link BundleContext}. The returned + * BundleContext can be used by the caller to act on behalf + * of this bundle. + * + *

+ * If this bundle is not in the {@link #STARTING}, {@link #ACTIVE}, or + * {@link #STOPPING} states or this bundle is a fragment bundle, then this + * bundle has no valid BundleContext. This method will + * return null if this bundle has no valid + * BundleContext. + * + * @return A BundleContext for this bundle or + * null if this bundle has no valid + * BundleContext. + * @throws java.lang.SecurityException If the caller does not have the + * appropriate AdminPermission[this,CONTEXT], and + * the Java Runtime Environment supports permissions. + * @since 1.4 + */ + public BundleContext getBundleContext(); +} Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/Bundle.java ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleActivator.java URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleActivator.java?rev=737043&view=auto ============================================================================== --- db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleActivator.java (added) +++ db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleActivator.java Fri Jan 23 07:05:47 2009 @@ -0,0 +1,89 @@ +/* + * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleActivator.java,v 1.14 2007/02/21 16:49:05 hargrave Exp $ + * + * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved. + * + * Licensed 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.osgi.framework; + +/** + * Customizes the starting and stopping of a bundle. + *

+ * BundleActivator is an interface that may be implemented when a + * bundle is started or stopped. The Framework can create instances of a + * bundle's BundleActivator as required. If an instance's + * BundleActivator.start method executes successfully, it is + * guaranteed that the same instance's BundleActivator.stop + * method will be called when the bundle is to be stopped. The Framework must + * not concurrently call a BundleActivator object. + * + *

+ * BundleActivator is specified through the + * Bundle-Activator Manifest header. A bundle can only specify a + * single BundleActivator in the Manifest file. Fragment bundles + * must not have a BundleActivator. The form of the Manifest + * header is: + * + *

+ * Bundle-Activator: class-name + * + *

+ * where class-name is a fully qualified Java classname. + *

+ * The specified BundleActivator class must have a public + * constructor that takes no parameters so that a BundleActivator + * object can be created by Class.newInstance(). + * + * @NotThreadSafe + * @version $Revision: 1.14 $ + */ + +public interface BundleActivator { + /** + * Called when this bundle is started so the Framework can perform the + * bundle-specific activities necessary to start this bundle. This method + * can be used to register services or to allocate any resources that this + * bundle needs. + * + *

+ * This method must complete and return to its caller in a timely manner. + * + * @param context The execution context of the bundle being started. + * @throws java.lang.Exception If this method throws an exception, this + * bundle is marked as stopped and the Framework will remove this + * bundle's listeners, unregister all services registered by this + * bundle, and release all services used by this bundle. + */ + public void start(BundleContext context) throws Exception; + + /** + * Called when this bundle is stopped so the Framework can perform the + * bundle-specific activities necessary to stop the bundle. In general, this + * method should undo the work that the BundleActivator.start + * method started. There should be no active threads that were started by + * this bundle when this bundle returns. A stopped bundle must not call any + * Framework objects. + * + *

+ * This method must complete and return to its caller in a timely manner. + * + * @param context The execution context of the bundle being stopped. + * @throws java.lang.Exception If this method throws an exception, the + * bundle is still marked as stopped, and the Framework will remove + * the bundle's listeners, unregister all services registered by the + * bundle, and release all services used by the bundle. + */ + public void stop(BundleContext context) throws Exception; +} Propchange: db/derby/code/trunk/java/stubs/felix/org/osgi/framework/BundleActivator.java ------------------------------------------------------------------------------ svn:eol-style = native