OSGi Fragment Bundles

Okay, in case it is not yet clear, Liferay 7 uses an OSGi container.

I know what you're thinking: "Well, Duh..."

The point is that OSGi is actually a standard and anything that works within OSGi will work within Liferay. You just need to understand the specs to make something of it.

For example, I'd like to talk about OSGi Fragment Bundles. There's actually stuff in the specs that cover what fragment bundles can do, how they will be treated by the container, etc.

The only way that Liferay typically presents a fragment bundle as a solution is for a JSP fragment, but there's actually some additional stuff that can be done with them.

OSGi Fragment Bundles

Fragment bundles are covered in chapter 3.14 of the OSGi Core 6.0.0 specification document.  In technical terms,

Fragments are bundles that can be attached to one or more host bundles by the framework. Attaching is done as part of resolving: the Framework appends the relevant definitions of the fragment bundles to the host's definitions before the host is resolved. Fragments are therefore treated as part of the host, including any permitted headers.

The idea here is that fragments can supplement the content of a host bundle, but cannot replace files from the host. Since the fragment is appended to the host, resources will always be loaded from the host bundle before they are loaded from the fragment.

This is counter to the old way Liferay used to do JSP hooks, where these hooks could actually replace any JSP or static file from the original bundle.  Fragments can only add new files, but not replace existing ones.

So you might now be wondering how the JSP files from a fragment bundle actually do override the files from the host bundle. The answer? Liferay magic. Well, not magic, per se, but there is special handling of JSP files by the Liferay systems to use a JSP file from a fragment before the host, but this is not normal OSGi Fragment Bundle behavior.

What good are they if they can only add files?

Actually you can do quite a bit once you understand that bit.

For example, I was recently trying to help a team override the notification template handling from the calendar-service module, a ServiceBuilder service module for the Liferay calendar. The team needed to replace some of the internal classes to add some custom logic and had been unsuccessful. They had seen my blog post on Extending Liferay OSGi Modules, but the warnings in the blog were taken to heart and they didn't want to go down that road unless it became necessary.

The calendar-service module has a bunch of internal classes that are instantiated and wired up using the internal Spring context set up for ServiceBuilder service modules. So the team needed to provide new template files, but in addition they needed custom classes to replace the instances wired up by Spring when setting up the context, a seemingly difficult ask.

The Spring aspects of the host module in addition to the appending nature of the fragment bundle handling actually makes this pretty easy to do...

First, create a fragment bundle using the host and version from the original.  For this override, it is com.liferay.calendar.service and rather than use a specific version, I opted for a range [2.3.0,3.0.0).

Next I added a new class, src/main/java/com/liferay/calendar/notification/impl/CustomEmailNotificationSender.java.  It was basically a copy of the original EmailNotificationSender class from the same package, I just added in a bunch of log statements to see that it was being used.  Note that I was actually free to use any package I wanted to here, it really wasn't that important.

Next I added a src/main/resources/META-INF/spring/calendar-spring-ext.xml file to the fragment bundle with a replacement bean definition.  Instead of instantiating the original EmailNotificationSender, I just had to instantiate my custom class:

<?xml version="1.0"?>

<beans
	default-destroy-method="destroy"
	default-init-method="afterPropertiesSet"
	xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"
>
	<!-- Replace the Liferay bean definition with our own. -->
	<bean class="com.liferay.calendar.notification.impl.NotificationSenderFactory" id="com.liferay.calendar.notification.impl.NotificationSenderFactory">
		<property name="notificationSenders">
			<map>
				<entry key="email">
					<bean class="com.liferay.calendar.notification.impl.CustomEmailNotificationSender" />
				</entry>
				<entry key="im">
					<bean class="com.liferay.calendar.notification.impl.IMNotificationSender" />
				</entry>
			</map>
		</property>
	</bean>
</beans>

So while I couldn't replace the old class, I could add a new class and a new Spring configuration file to replace the old definition with one that used my class.

Once the fragment was built and deployed, it was working as expected.  The project at this state is available here: https://github.com/dnebing/calendar-override

Additionally the team needed to alter the template files.  This was accomplished by adding a src/main/resources/portlet-ext.properties file with a replacement property key for the template to replace pointing to a new file also included in the fragment bundle.  Since the original portlet.properties file has an "include-and-override" line to pull in portlet-ext.properties, when the fragment bundle is appended to the host the replacement property key will be used and the new file from the fragment bundle will be loaded.

What Else Can I Use Fragments For?

While I don't have working code to demonstrate each of these, the working example makes me think you can use a fragment bundle to extend an existing Liferay ServiceBuilder service module.

Since ServiceBuilder modules are Spring-based and the default Spring configuration declaring the service is in META-INF/spring/module-spring.xml, we can use a fragment bundle to add a META-INF/spring/module-spring-ext.xml file and replace a default wiring to a service instance to a custom class, one that perhaps extends the original but overrides whatever code from the original. Spring would instantiate our class, it would have the right heirarchy and should make everything work.

This wouldn't work for services from portal-impl since they are not loaded by OSGi ServiceBuilder host modules, but it should work for those that are deployed this way.

Another idea is that it could be used to override static .css and/or .js files from the host bundle. Well, not override per se, but introduce new files that, in addition to a Configuration Admin config file, could use the replacements in lieu of the originals.

So, for example, calendar-web has a /css/main.css (actually main.scss file, but it will be built to main.css) file that is pulled in by the portlet. We could use a fragment bundle to add a new file, /css/main-ext.scss file. It could either have everything from main.scss with your changes or it could just contain the changes depending upon how you wanted to manage it going forward.  As a new file, it could be loaded if the portal was going for the file.

The original file is pulled in by the portal due to the properties on the CalendarPortlet annotation:

@Component(
	immediate = true,
	property = {
		"com.liferay.portlet.add-default-resource=true",
		"com.liferay.portlet.css-class-wrapper=calendar-portlet",
		"com.liferay.portlet.display-category=category.collaboration",
		"com.liferay.portlet.friendly-url-mapping=calendar",
		"com.liferay.portlet.header-portlet-css=/css/main.css",
		"com.liferay.portlet.icon=/icons/calendar.png",
		"com.liferay.portlet.preferences-owned-by-group=true",
		"com.liferay.portlet.preferences-unique-per-layout=false",
		"javax.portlet.display-name=Calendar",
		"javax.portlet.expiration-cache=0",
		"javax.portlet.init-param.copy-request-parameters=true",
		"javax.portlet.init-param.view-template=/view.jsp",
		"javax.portlet.name=" + CalendarPortletKeys.CALENDAR,
		"javax.portlet.resource-bundle=content.Language",
		"javax.portlet.security-role-ref=administrator,power-user,user",
		"javax.portlet.supports.mime-type=text/html"
	},
	service = Portlet.class
)
public class CalendarPortlet extends MVCPortlet {

So we would need the portlet to use a new set of properties that specifically changed from /css/main.css to /css/main-ext.css. This we can do by adding a file to $LIFERAY_HOME/osgi/configs/com.liferay.calendar.web.internal.portlet.CalendarPortlet.cfg file. This file format as defined here: https://dev.liferay.com/discover/portal/-/knowledge_base/7-0/understanding-system-configuration-files and basically allows you to create a file to replace configuration property key values w/ custom versions.

So in our file we would add a line, com.liferay.portlet.header-portlet-css=["/css/main.css","/css/main-ext.css"]. This is the format for including both files, if you just wanted the one file it would simply be com.liferay.portlet.header-portlet-css="/css/main-ext.css". This file would need to be manually deployed to the osgi/configs directory, but once it is done and combined with the fragment bundle, the main.css file and main-ext.css file would be included.

This is the same kind of process that you would use to handle static javascript files pulled in by the portlet's @Component annotation properties.

Conclusion

So OSGi Fragment Bundles can be used for things beyond simple JSP fragment bundles.

I'm hoping what I presented here gives you some ideas on how you might solve problems that you're facing with "overriding" Liferay default functionality.

If you have some ideas, please share below as they may be helpful to others struggling w/ similar issues.

 

Blogs
Well, I add a link to my blog post (https://web.liferay.com/it/web/glassofwhiskey/blog/-/blogs/blueprint-and-osgi-fragments-for-granular-module-extension), where I explain how to use a combination of OSGi Fragments and Blueprint specification to override Components avoiding unnecessary code and resources duplication. Hope it can help someone
[...] I have been working on adding CKEditor plugins to the Alloy Editor in Liferay DXP and figured I would share what I found. Specifically I was trying to add the YouTube Plugin. There are some... [...] Read More