fix: make CorbanameURLContextFactory an ApplicationPrereq

dev/com.ibm.ws.app.manager.lifecycle/src/com/ibm/wsspi/application/lifecycle/ApplicationPrereq.java

@@ -1,10 +1,10 @@
 /*******************************************************************************
- * Copyright (c) 2020 IBM Corporation and others.
+ * Copyright (c) 2020,2024 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-2.0/
- * 
+ *
  * SPDX-License-Identifier: EPL-2.0
  *
  * Contributors:
@@ -13,12 +13,118 @@
 package com.ibm.wsspi.application.lifecycle;
 
 /**
- * This a marker interface for Service components that must be present before wsspi.applications are started.  
- * 
- * Implementors must also provide a config element in their defaultInstances.xml as follows:
- * {@code
- *   <com.ibm.wsspi.application.lifecycle.ApplicationPrereq className="fully.qualified.ClassName" />
- * }
+ * A marker interface for service components indicating
+ * they must be present before applications are started.
+ * <p>
+ * Liberty's processing of configuration and metatype will discover
+ * these declarations and wait for the configured services before
+ * allowing applications to start.
+ * </p>
+ *
+ * Every implementor must observe the following conventions:
+ * <ol>
+ *   <li>Edit the {@code bnd.bnd} for the bundle to instruct bnd appropriately:
+ *     <ul>
+ *       <li>Process the class for declarative services annotations:
+ *         <pre>
+ * -dsannotations: com.acme.Widget
+ *         </pre>
+ *       </li>
+ *       <li>Add the metatype and default instances to the bundle:
+ *         <pre>
+ * Include-Resource: OSGI-INF=resources/OSGI-INF
+ *         </pre>
+ *       </li>
+ *       <li>Declare the default instances (if required &mdash; see below):
+ *         <pre>
+ * IBM-Default-Config: OSGI-INF/wlp/defaultInstances.xml
+ *         </pre>
+ *       </li>
+ *       <li>Add the app manager lifecycle bundle to the build path:
+ *         <pre>
+ * -buildpath: com.ibm.ws.app.manager.lifecycle;version=latest
+ *         </pre>
+ *       </li>
+ *     </ul>
+ *   </li>
+ *   <li>The implementation must declare itself as a declarative services (DS) component.
+ *     <ul>
+ *       <li>The component declaration must provide {@link ApplicationPrereq} as a service.<br>
+ *         <em>
+ *         If this is not done, the configured component instance will never be discovered, and applications will not start up.
+ *         </em>
+ *       </li>
+ *       <li>The component declaration must require configuration.</li>
+ *     </ul>
+ *     e.g.:
+ *     <pre>
+ * package com.acme;
+ * {@code @Component}(
+ *         service = ApplicationPrereq.class,
+ *         configurationPolicy = REQUIRE,
+ *         configurationPid = "com.acme.Widget",
+ *         property = "service.vendor=Acme")
+ * public class Widget implements ApplicationPrereq {&hellip;}
+ *     </pre>
+ *     <em>
+ *       Note: Components can be declared in the Java source or in the {@code bnd.bnd} file. <br>
+ *       Verify the component xml in the generated bundle,
+ *       e.g. {@code OSGI-INF/com.acme.Widget.xml}
+ *     </em>
+ *   </li>
+ *   <li>
+ *     The implementing bundle must provide an {@code OCD} and a {@code Designate}
+ *     for the configuration in an XML file in {@code resources/OSGI-INF/metatype/},
+ *     usually {@code metatype.xml}.
+ *     <ul>
+ *       <li>the OCD must declare its objectClass to be {@link ApplicationPrereq}<br>
+ *         e.g.
+ *         <pre>
+ * {@code <OCD id="com.acme.Widget"}
+ *      ibm:alias="widget"
+ *      name="%widget"
+ *      description="%widget.desc"
+ *      ibm:objectClass="com.ibm.wsspi.application.lifecycle.ApplicationPrereq" {@code >}
+ * &vellip;
+ * {@code </OCD>}
+ *         </pre>
+ *         <em>
+ *         Declaring the objectClass correctly allows every configuration of this OCD to be discovered.
+ *         Application containers will start only after the configured component instances become available.
+ *         </em>
+ *       </li>
+ *       <li>
+ *         <strong>Either</strong> the Designate must use a factoryPid instead of a pid,
+ *         <pre>
+ * {@code <Designate factoryPid="com.acme.Widget">}
+ *   {@code <Object ocdref="com.acme.Widget" />}
+ * {@code </Designate>}
+ *         </pre>
+ *       </li>
+ *       <li>
+ *         <strong>Or</strong> the OCD must contain a required AD without a default value:
+ *         <pre>
+ * {@code <OCD} &hellip; {@code >}
+ *   {@code <AD id="id" name="%widget.id" required="true" type="String"/>}
+ * {@code </OCD>}
+ *         </pre>
+ *         <em>
+ *         If the delegate uses a pid and the OCD has no required non-default AD,
+ *         Liberty's configuration processing may not be invoked for this OCD,
+ *         and the counting of application prereqs may fail.
+ *         <strong>This can be very difficult to debug!</strong>
+ *         </em>
+ *       </li>
+ *     </ul>
+ *   </li>
+ *   <li>The configuration may be user-specified in the server.xml or provided in the bundle's default instances:
+ *     <pre>
+ * {@code <server>}
+ *   {@code <widget />}
+ * {@code </server>}
+ *     </pre>
+ *   </li>
+ * </ol>
  */
 public interface ApplicationPrereq {
 }

dev/com.ibm.ws.jndi.iiop/bnd.bnd

@@ -1,10 +1,10 @@
 #*******************************************************************************
-# Copyright (c) 2017,2021 IBM Corporation and others.
+# Copyright (c) 2017,2024 IBM Corporation and others.
 # All rights reserved. This program and the accompanying materials
 # are made available under the terms of the Eclipse Public License 2.0
 # which accompanies this distribution, and is available at
 # http://www.eclipse.org/legal/epl-2.0/
-# 
+#
 # SPDX-License-Identifier: EPL-2.0
 #
 # Contributors:
@@ -21,7 +21,7 @@ Bundle-Description: This bundle provides a way to access CosNaming via JNDI; ver
 WS-TraceGroup: Naming
 
 # For each exported package, create (in that package) a package-info.java
-# file, and place an @version javadoc tag in package-level javadoc. 
+# file, and place an @version javadoc tag in package-level javadoc.
 # Append ";provide:=true" if this bundle also provides an implementation
 # for the exported API.
 
@@ -33,6 +33,9 @@ Import-Package: \
  javax.rmi.*;version="[2.4,3.0)", \
  *
 
+Include-Resource: OSGI-INF=resources/OSGI-INF
+IBM-Default-Config: OSGI-INF/wlp/defaultInstances.xml
+
 -dsannotations-inherit: true
 -dsannotations: com.ibm.ws.jndi.iiop.*UrlContextFactory
 

dev/com.ibm.ws.jndi.iiop/resources/OSGI-INF/metatype/metatype.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Copyright (c) 2024 IBM Corporation and others.
+    All rights reserved. This program and the accompanying materials
+    are made available under the terms of the Eclipse Public License 2.0
+    which accompanies this distribution, and is available at
+    http://www.eclipse.org/legal/epl-2.0/
+
+    SPDX-License-Identifier: EPL-2.0
+
+    Contributors:
+        IBM Corporation - initial API and implementation
+ -->
+<metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.1.0"
+                   xmlns:ibm="http://www.ibm.com/xmlns/appservers/osgi/metatype/v1.0.0"
+                   xmlns:ibmui="http://www.ibm.com/xmlns/appservers/osgi/metatype/ui/v1.0.0"
+                   localization="OSGI-INF/l10n/metatype">
+
+  <Designate pid="com.ibm.ws.jndi.iiop.CorbanameUrlContextFactory">
+    <Object ocdref="com.ibm.ws.jndi.iiop.CorbanameUrlContextFactory" />
+  </Designate>
+
+  <OCD id="com.ibm.ws.jndi.iiop.CorbanameUrlContextFactory" name="internal" description="internal use only"
+       ibm:objectClass="com.ibm.wsspi.application.lifecycle.ApplicationPrereq">
+    <AD id="id" name="internal" description="internal use only" type="String"  required="true" />
+  </OCD>
+
+
+</metatype:MetaData>
+

dev/com.ibm.ws.jndi.iiop/resources/OSGI-INF/wlp/defaultInstances.xml

@@ -0,0 +1,15 @@
+<!--
+    Copyright (c) 2024 IBM Corporation and others.
+    All rights reserved. This program and the accompanying materials
+    are made available under the terms of the Eclipse Public License 2.0
+    which accompanies this distribution, and is available at
+    http://www.eclipse.org/legal/epl-2.0/
+
+    SPDX-License-Identifier: EPL-2.0
+
+    Contributors:
+        IBM Corporation - initial API and implementation
+ -->
+<server>
+  <com.ibm.ws.jndi.iiop.CorbanameUrlContextFactory id="CorbanameUrlContextFactory" />
+</server>

dev/com.ibm.ws.jndi.iiop/src/com/ibm/ws/jndi/iiop/CorbanameUrlContextFactory.java

@@ -1,20 +1,19 @@
 /*******************************************************************************
- * Copyright (c) 2017 IBM Corporation and others.
+ * Copyright (c) 2017,2024 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-2.0/
- * 
+ *
  * SPDX-License-Identifier: EPL-2.0
  *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 package com.ibm.ws.jndi.iiop;
 
-import static org.osgi.service.component.annotations.ConfigurationPolicy.IGNORE;
+import static org.osgi.service.component.annotations.ConfigurationPolicy.REQUIRE;
 
-import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.util.BitSet;
 import java.util.regex.Matcher;
@@ -26,10 +25,18 @@
 
 import com.ibm.websphere.ras.Tr;
 import com.ibm.websphere.ras.TraceComponent;
+import com.ibm.wsspi.application.lifecycle.ApplicationPrereq;
 import com.ibm.wsspi.application.lifecycle.ApplicationRecycleComponent;
 
-@Component(configurationPolicy=IGNORE,property={"service.vendor=ibm","osgi.jndi.url.scheme=corbaname"})
-public class CorbanameUrlContextFactory extends UrlContextFactory implements ObjectFactory, ApplicationRecycleComponent {
+/**
+ * One of the context factories should be an {@link ApplicationPrereq}
+ * to represent this bundle being up and running.
+ * This (the most commonly used one) was chosen.
+ */
+
+
+@Component(configurationPolicy=REQUIRE,property={"service.vendor=ibm","osgi.jndi.url.scheme=corbaname"})
+public class CorbanameUrlContextFactory extends UrlContextFactory implements ObjectFactory, ApplicationRecycleComponent, ApplicationPrereq {
     static class Escaper{
         static final TraceComponent tc = Tr.register(CorbanameUrlContextFactory.Escaper.class);
         private static final Pattern PERCENT_TRIPLET = Pattern.compile("%(?:[0-9a-f]{2}|[0-9A-F]{2})");
@@ -88,7 +95,7 @@ public static String escapeCorbanameUrlIfNecessary(String url) {
                 // escape dots
                 n = n.replaceAll("\\.", "\\\\.");
 
-                // 
+                //
                 sn.append(n).append("/");
             }
 
@@ -118,8 +125,8 @@ public static String escapeCorbanameUrlIfNecessary(String url) {
             return escaped.toString();
         }
 
-        
+
     }
-    
-    
+
+
 }