Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Configuring Prototypes

Configuring Prototypes

A prototype bundle is configured in one central place: a custom Guice Helix module. In the module, the Guice Context for local dependency injection and OSGi service binding is configured, which enables dependency injection in prototypes. PermissionParameterStrategy objects are also initialized in the custom Guice Helix module, which are used for Cortex's Authorization System.

Authorizing Helix Prototype Bundles

Authorization for prototype bundles follows the same Authorization patterns described in Cortex Authorization, with two notable distinctions:

  • The location of the properties file is resources, as opposed to resources/OSGI-INF/config.
  • The permission string is slightly different when containing a resource's own URI-part. The URI-partneeds to be fully qualified: for example, a legacy URI-part, :{scope}:{profileId} needs to be :{base.scope}:{profiles.profile-id} in Helix programming model prototypes.

Configuration by AbstractHelixModule Extension

You can configure the Guice Helix module by creating an extension of the AbstractHelixModule class. By doing this, you can register PermissionParameterStrategy, local classes for dependency injection, and import OSGi services.

When extending AbstractHelixModule, Remember to annotate the custom Guice Helix module with @Named. Failing to do so may prevent your resource wiring from being loaded, which will prevent the resource itself from being registered. If your module has depenendecies, this might show up as unresolved bundles or missing services otherwise nothing will appear broken.

  • The configurePrototypes method wires up the local Guice Context for dependency injection of local managed classes and remote OSGi services.
  • The resourceName method needs to be implemented to return the resource's family name, which is needed to initialize the permissions system for the bundle.
  • The optional registerParameterResolvers methods registers PermissionParameterStrategy objects to specific URI-parts.

Configuring local Guice context

To configure the local Guice context, override the configurePrototypes method in an extension of AbstractHelixModule.

To register local JSR330 annotated classes to Guice's dependency injection context, you must wire them manually. Add the following bind statement to configurePrototypes for each class that should be bound:

  bind(MyConverter.class).toInstance(new MyConverterImpl());
        

The bind statement can also be used to bind OSGi services provided by other bundles to the local Guice Context. The Peaberry framework then helps to bridge between the OSGi context and the Guice context. The following is an example of how this is done:

   bind(CustomValidationService.class).toProvider(service(CustomValidationService.class).single());
        

Configuring URI-part Permission Verification

Cortex is able to to do permission checking based on specific URI-parts. For more informaiton, see Cortex Authorization.

PermissionParameterStrategy objects play a central role in the Cortex Authorization system. Classes implementing this interface are responsible for creating the logged-in user specific URI-part String for a specific URI-part. This will then be verified against the actual URI-part String provided in the HTTP request.

If the URI-part String needs to be matched against a collection of logged-in user specific URI-part strings, AbstractCollectionValueStrategy, which implements PermissionParameterStrategy should be extended. An example of extending AbstractCollectionValueStrategy is the cart-id URI-part, where a user can be associated with multiple cart-id resources.

To register a new PermissionParameterStrategy add the resolvers.addBinding statement to the overridden registerParameterResolvers method:

  @Override
  protected void registerParameterResolvers(final MapBinder<String, PermissionParameterStrategy> resolvers) {
    super.registerParameterResolvers(resolvers);
    resolvers.addBinding(ProfileIdentifier.PROFILE_ID).toInstance(new ProfileIdParameterStrategy());
    }
        

Where ProfileIdentifier.PROFILE_ID is the profile-id URI-part identifier. In this case, ProfileIdParameterStrategy cheks the permissions on that URI-part.

Exposing an OSGi service

To expose an OSGi service in a prototype bundle, use OSGi's declarative service (DS) annotations @Component and @Reference on the service:

  @Component
  public class CustomValidationServiceImpl implements CustomValidationService {
    @Reference
    private MyCeService ceService;
  }       
      

Where @Component marks a bean as an OSGi service and @Reference injects another (internal or external) OSGi service on which the OSGi service is dependent on. Refer to the OSGi specification to learn more about the semantics and usage of these annotations.