better detail in REST API response when posting ZIP

preserves backwards compatibility, adding a detail=true flag which gives richer info.
see extended comment in code.

also fixes bug where the added/changed items weren't actually listed.

Author: ahgittin

core/src/main/java/org/apache/brooklyn/core/mgmt/ha/OsgiManager.java

@@ -372,12 +372,11 @@ public synchronized Bundle registerBundle(CatalogBundle bundleMetadata) {
     // possibly remove that other capability, so that bundles with BOMs _have_ to be installed via this method.
     // (load order gets confusing with auto-scanning...)
     public List<? extends CatalogItem<?,?>> loadCatalogBom(Bundle bundle) {
-        List<? extends CatalogItem<?, ?>> catalogItems = MutableList.of();
-        loadCatalogBom(mgmt, bundle, catalogItems);
-        return catalogItems;
+        return MutableList.copyOf(loadCatalogBom(mgmt, bundle));
     }
 
-    private static Iterable<? extends CatalogItem<?, ?>> loadCatalogBom(ManagementContext mgmt, Bundle bundle, Iterable<? extends CatalogItem<?, ?>> catalogItems) {
+    private static Iterable<? extends CatalogItem<?, ?>> loadCatalogBom(ManagementContext mgmt, Bundle bundle) {
+        Iterable<? extends CatalogItem<?, ?>> catalogItems = MutableList.of();
         if (!BrooklynFeatureEnablement.isEnabled(BrooklynFeatureEnablement.FEATURE_LOAD_BUNDLE_CATALOG_BOM)) {
             // if the above feature is not enabled, let's do it manually (as a contract of this method)
             try {

rest/rest-api/src/main/java/org/apache/brooklyn/rest/api/CatalogApi.java

@@ -88,13 +88,22 @@ public Response createFromYaml(
             @Valid String yaml);
 
     @Beta
+    /* TODO the polymorphic return type dependent on 'detail' is ugly, 
+     * but we're stuck in this API because backwards compatibility expects the types map
+     * whereas typical usage wants more feedback. we should introduce a 
+     * /registry and/or /types and/or /bundles endpoint that always provides details
+     * (and an approach to handling types more aligned with BrooklynTypeRegistry and OSGi bundling).
+     * Not too concerned here as this method is beta and the above switch will probably naturally happen soon. 
+     * The main client who cares about this is the Go CLI. */
     @POST
     @Consumes({"application/x-zip", "application/x-jar"})
     @ApiOperation(
             value = "Add a catalog items (e.g. new type of entity, policy or location) by uploading a ZIP/JAR archive.",
             notes = "Accepts either an OSGi bundle JAR, or ZIP which will be turned into bundle JAR. Bother format must "
                     + "contain a catalog.bom at the root of the archive, which must contain the bundle and version key."
-                    + "Return value is map of ID to CatalogItemSummary.",
+                    + "Return value is map of ID to CatalogItemSummary unless detail=true is passed as a parameter in which "
+                    + "case the return value is a BundleInstallationRestResult map containing the types map in types along "
+                    + "with a message, bundle, and code.",
             response = String.class,
             hidden = true)
     @ApiResponses(value = {
@@ -106,7 +115,10 @@ public Response createFromArchive(
                     name = "archive",
                     value = "Bundle to install, in ZIP or JAR format, requiring catalog.bom containing bundle name and version",
                     required = true)
-            byte[] archive);
+            byte[] archive,
+            @ApiParam(name="detail", value="Provide a wrapping details map", required=false)
+            @QueryParam("detail") @DefaultValue("false")
+            boolean detail);
 
     @Beta
     @POST

rest/rest-resources/src/main/java/org/apache/brooklyn/rest/resources/CatalogResource.java

@@ -45,7 +45,6 @@
 import org.apache.brooklyn.api.policy.PolicySpec;
 import org.apache.brooklyn.api.sensor.Enricher;
 import org.apache.brooklyn.api.sensor.EnricherSpec;
-import org.apache.brooklyn.api.typereg.ManagedBundle;
 import org.apache.brooklyn.api.typereg.RegisteredType;
 import org.apache.brooklyn.core.catalog.CatalogPredicates;
 import org.apache.brooklyn.core.catalog.internal.CatalogItemComparator;
@@ -130,7 +129,7 @@ public Response createFromUpload(byte[] item) {
             return createFromYaml(new String(item));
         }
 
-        return createFromArchive(item);
+        return createFromArchive(item, false);
     }
 
     @Override
@@ -159,7 +158,7 @@ public static class BundleInstallationRestResult {
         // as Osgi result, but without bundle, and with maps of catalog items installed
 
         String message;
-        ManagedBundle metadata;
+        String bundle;
         OsgiBundleInstallationResult.ResultCode code;
 
         Map<String,Object> types;
@@ -172,7 +171,7 @@ public String getMessage() {
         public static BundleInstallationRestResult of(OsgiBundleInstallationResult in, ManagementContext mgmt, BrooklynRestResourceUtils brooklynU, UriInfo ui) {
             BundleInstallationRestResult result = new BundleInstallationRestResult();
             result.message = in.getMessage();
-            result.metadata = in.getMetadata();
+            result.bundle = in.getMetadata().getVersionedName().toString();
             result.code = in.getCode();
             if (in.getCatalogItemsInstalled()!=null) {
                 result.types = MutableMap.of();
@@ -191,7 +190,7 @@ public static BundleInstallationRestResult of(OsgiBundleInstallationResult in, M
 
     @Override
     @Beta
-    public Response createFromArchive(byte[] zipInput) {
+    public Response createFromArchive(byte[] zipInput, boolean detail) {
         if (!Entitlements.isEntitled(mgmt().getEntitlementManager(), Entitlements.ROOT, null)) {
             throw WebResourceUtils.forbidden("User '%s' is not authorized to add catalog item",
                 Entitlements.getEntitlementContext().user());
@@ -205,7 +204,8 @@ public Response createFromArchive(byte[] zipInput) {
                 .data(BundleInstallationRestResult.of(result.getWithoutError(), mgmt(), brooklyn(), ui)).build().asJsonResponse();
         }
 
-        return Response.status(Status.CREATED).entity( BundleInstallationRestResult.of(result.get(), mgmt(), brooklyn(), ui) ).build();
+        BundleInstallationRestResult resultR = BundleInstallationRestResult.of(result.get(), mgmt(), brooklyn(), ui);
+        return Response.status(Status.CREATED).entity( detail ? resultR : resultR.types ).build();
     }
 
     private Response buildCreateResponse(Iterable<? extends CatalogItem<?, ?>> catalogItems) {