liferay-plugin-package.properties vs liferay-plugin-package.xml

[Kristof Verbraeken, modificado hace 14 años.]

Hi all,

I've got a question about plug-in information you can provide about a theme, portlet, etc.

You can do this with liferay-plugin-package.properties or liferay-plugin-package.xml, but which file is really prefered to use? Is there any difference between these files?

Also, I noticed (in the plug-ins SDK) that with the sample layout templates, the liferay-plugin-package.xml is always used. With themes, portlets and hooks, liferay-plugin-package.properties is always used. Why is this so?

Thanks for any clarification!

Kind regards,
Kristof

[Advait Trivedi, modificado hace 10 años.]

Please see this thread, https://www.liferay.com/community/forums/-/message_boards/message/8274292
As per this thread, XML provides information related to the plugin, while properties file is mainly useful for defining dependencies.

[sushil patidar, modificado hace 10 años.]

Kristof Verbraeken:

Hi all,

I've got a question about plug-in information you can provide about a theme, portlet, etc.

You can do this with liferay-plugin-package.properties or liferay-plugin-package.xml, but which file is really prefered to use? Is there any difference between these files?

Also, I noticed (in the plug-ins SDK) that with the sample layout templates, the liferay-plugin-package.xml is always used. With themes, portlets and hooks, liferay-plugin-package.properties is always used. Why is this so?

Thanks for any clarification!

Kind regards,
Kristof

Hi Kristoff,
Generally properties file is preferred ,because this the file which exists in your eclipse plugin. And i assume xml file is generated on portlet deployement and contains all the properties of the properties file in xml format.

Regards

[Vilmos Papp, modificado hace 10 años.]

Hi,

If you would like to publish your plugin to marketplace based on the Developer Guide:

WAR (.war) files:
WARs must contain a WEB-INF/liferay-plugin-package.properties file.
WARs must not contain any WEB-INF/liferay-plugin-package.xml file.

[Petr Bodnár, modificado hace 6 años.]

Hi all,

(Note: Talking just about the recent 6.2.5 GA 6 Liferay version for simplicity.)

so what we've got here after all the years of this pending question? In short, no actually useful answer, considering the various forums and documentation. Moreover, the topic gets even more complicated when putting Liferay IDE and "deployed war naming conventions" into the play. The one and only reliable source of knowledge seems to be the source code. Still, some answers can be simply provided only by the Liferay authors. The resulting effect is that there is apparently no clear concept even among the Liferay staff on this deployment topic. Lets try to split it down now...

1. Answers from forums

Answer #1 here, misleading: "[...] As per this thread, XML provides information related to the plugin, while properties file is mainly useful for defining dependencies." -- in reality, either XML, or properties is parsed by the deployer and you can put approx. the same information to both (see below)

Answer #2 here, misleading: "Generally properties file is preferred ,because this the file which exists in your eclipse plugin. And i assume xml file is generated on portlet deployement and contains all the properties of the properties file in xml format." -- in reality, there is no such XML generated on portlet deployment. Also the notice about Eclipse plugin (meaning Liferay IDE, probably) is not actually explaining anything.

Answer #3 here, correct, but not really that useful / explanatory: "If you would like to publish your plugin to marketplace based on the Developer Guide: [...] WARs must not contain any WEB-INF/liferay-plugin-package.xml file."

From the forum Liferay "Plugin Packages" - What are they? Documentation?:

Answer #4 there, misleading (even if maybe valid back in 2011?): "liferay-plugin-package.properties a dependencies file for the plugin.
liferay-plugin-package.xml is an information file for the portlet." -- as mentioned above and explained below, this is simply not actually true

2. Answers from documentation

Firstly, there doesn't seem to be any documentation explaining the difference between XML and properties. Secondly, there is the page documenting the properties variant, but it is utterly incomplete as to this date - see below.

3. Hints coming from issues from the bugtracker

LPS-15181 Portlets can be deployed without -portlet postfix: when you look at the issue history, you need to be simply confused from what was going on there. Moreover, as explained below, you won't have the reported problem when using the XML variant.

LPS-30327 Plugin bundle wont deploy: this is about adding support for "module-version" into the properties variant. This is nice, but as in the case of some other important settings added "from XML to properties variant", these settings are not described in any kind of documentation, but still, they are supported!

4. What it actually does

Just look into the source code of PluginPackageUtil.java, starting from the _readPluginPackageServletContext() method. You can clearly see the XML variant is used and parsed. Only when it is not present, the properties variant gets parsed. Moreover, if that properties parsing fails (returns null), a default metadata is prepared, while even reading some selected properties from war's MANIFEST.MF.

So the key method is the parsing _readPluginPackageProperties(). When it doesn't find some of the predefined suffixes in the war's name (i. e. '-portlet', '-theme' etc.), it simply "gives up" and returns null. Now try to name your project 'my-portlets' and deploy it via Liferay IDE - you'll get a nasty NoSuchElement exception (and your potential hook JSPs won't get deployed), because the project gets deployed as 'my-portlets-portlet' and the parsing method is not smart enough to find out that '-portlet' is not really the version of your project. The final thing to notice is that the method reads more settings from the file than documented (like e. g. 'module-version').

Finally, when you let Liferay IDE generate a new project (from a Maven archetype), it creates the project with the properties variant.

5. What we still need to know

Apart from being happy if any of the described findings is confirmed / corrected, there are still the following pending questions which should be answered by Liferay authors at best:

1. There are many indications the XML variant is the deprecated one. On the other side it seems to support a bit more stuff than the properties (features which are not wanted anymore?). Can the authors confirm this? If it really is, why isn't it documented anywhere?

2. Where comes the "requirement" of having the war named according to a convention (i. e. ending on '-portlet', '-theme' etc.) from? And, provided it is necessary, why the properties variant cannot simply have comma separated "types" setting instead, as the XML does? Is the naming restriction really necessary when the various deployers (like e. g. for hook) look at the appropriate meta files instead anyway?

3. A very similar question - why Liferay IDE since support for 6.2 always deploys one's project with the suffix (just google for it, you will find just unanswered forums like this one)? If the convention is really mandatory (it doesn't seem to be, hopefully!), why don't Liferay authors clearly say that and explain why?

[Andrew Jardine, modificado hace 6 años.]

Hi Petr,

I don't have the answer to your question to be honest, and it seems like you might have dug up most of it yourself. Just speculating here, but it feels almost like a backwards compatibility thing (though I have nothing to prove that statement). I suspect that the XML format was perhaps the way you did it way back once upon a time and that perhaps the properties was a new feature that is now the preferred or recommended approach (since the archetypes generate it and not the xml file for you). Remember, Liferay has been around for a dogs age in terms of software so you will come across things in the codebase that might be a little head scratching or seem "out of date". There have been other threads, for example, complaining about Liferay's use of struts -- and at some point you need to consider the cost/benefit of tearing out a feature to replace it with the latest and greatest (today) without knowing about tomorrow. But that's another subject.

For your point about the naming conventions and issue with generated/deployed plugins -- I ran into that one two a few years back. I actually opened a JIRA for it too. I tried to create a theme plugin call xxx-web-theme, because we thought we might have a separate theme for mobile. What I discovered, as you did, was that the theme and portlet deployers care about the context names. Annoying I agree, but, by the same token, from a semantics perspective it does make sense. I think we can agree that it is a good practice to name your plugin projects post fixed by their type. It makes it easy to identify (immediately at a glance) what the plug is used for. As for the name you referenced, adding my-portlet as your name, yes, that sucks but it has been long outlined (starting back with ANT) that when you create a new project you should omit the plugin type from the name. I'm not excusing it, just pointing out that it was noted.

To make things even more confusion for you, once you move into the world of 7, you won't have those files at all anymore! In the brave new world of OSGi, all these goodies that we are accustomed to spreading out across multiple config files get mashed into the bnd files.

I definitely applaud your curiosity, and your frustration with the lack of clarity on the answers. As you said, and I agree, most of the time the only way to get the truth is to dig into the code. Just don't dig too deep on this one unless all you care about is the curiosity factor.

[David H Nebinger, modificado hace 6 años.]

Why is this still a thing?

No one is supposed to be creating or editing the XML file. Liferay will do that during deployment. Anyone creating or editing the XML file should not be doing it.








Come meet me at the 2017 LSNA!

[Andrew Jardine, modificado hace 6 años.]

+1 for that. The fact that you DON'T have to write XML, to me is the very reason to just shrug your shoulders and accept that black box for what it is. But sometimes one's curiosity can get the better or them -- and you can't fault the man for that!

Bottom line, it seems, is ...

1. No one seems really sure why both are there.
2. Any chance to avoid writing XML, just accept it an move on.
3. Make sure that you names your plugins semantically, if for no other reason than because it's the right way to do it.
4. When you are getting conflicting answers --just go read the code. You'll get more context and a better understanding anyway.
5. Start learning/working with LR7 as it is the future anyway. (leave the past in the past)

[David H Nebinger, modificado hace 6 años.]

Andrew Jardine:

+1 for that. The fact that you DON'T have to write XML, to me is the very reason to just shrug your shoulders and accept that black box for what it is. But sometimes one's curiosity can get the better or them -- and you can't fault the man for that!

you're right, I guess my tone might have been off?

1. No one seems really sure why both are there.

I think the portal uses the XML version, but it builds that out during deploy and uses the properties file for the bulk of the details, but I do believe it was meant to be an internal-only file that was not intended for developers to create/modify. It may have been allowed at one point, but as seen in the marketplace docs it is no good any more.

3. Make sure that you names your plugins semantically, if for no other reason than because it's the right way to do it.

The Liferay hot deploy depends upon plugin naming actually. If you don't use the right plugin suffix, some hot deploys will actually not work right, but that can be app server dependent.

For example, a few years ago I was running Liferay on TCat and our plugin wars were just not working. Come to find out that the TCat profiles were created to specifically handle Liferay plugins based on suffix, if they didn't have the right suffix then TCat was not handling them correctly.









Come meet me at the 2017 LSNA!

[Andrew Jardine, modificado hace 6 años.]

One thing that I noticed, but never dug into was that there are sometimes statements in the log that reference a missing plugin package.xml file -- I am trying to remember which plugin seems to generate it consistently and I want to say that it is either the hook or the theme. Like I said, I've never dug into it though because it hasn't ever cause the undeploy to fail.

[Petr Bodnár, modificado hace 6 años.]

Hi,

thanks a lot for your feedback, even though it seems I can't actually expect any documentation efforts in this regard... Maybe only if I file a JIRA ticket for that ;)

Currently I don't have much time to dig deeper into this topic, so only just quickly...

1)

Why is this still a thing?

No one is supposed to be creating or editing the XML file. Liferay will do that during deployment. Anyone creating or editing the XML file should not be doing it.

For example because of legacy projects maintenance, confusion when working with Liferay IDE vs. when deploying manually?

2)

I've tested freshly a classic deployment without using Liferay IDE (as IDE apparently bypasses the process by deploying "tuned" app directly into the server) and you are right that the Liferay deployer actually does create the XML (if not present in the deployed war), although this doesn't seem to be the case for the pre-6.2 versions of Liferay. The deployer also "magically" renames "my-portlets" to "my-portlet" (setting the <recommended-deployment-context> in the XML) => one needs to search in some other Liferay source codes to really find out what's going on here...

[Petr Bodnár, modificado hace 6 años.]

Andrew Jardine:

One thing that I noticed, but never dug into was that there are sometimes statements in the log that reference a missing plugin package.xml file -- I am trying to remember which plugin seems to generate it consistently and I want to say that it is either the hook or the theme. Like I said, I've never dug into it though because it hasn't ever cause the undeploy to fail.

Yes, this is described in detail here: https://web.liferay.com/community/forums/-/message_boards/message/31431930. It happens exactly when there is the properties file, but the war is not named as "*-portlet", for example. And as described there, the error won't happen when you've got appropriate MANIFEST.MF included:

		String version = attributes.getValue("Implementation-Version");

		if (Validator.isNull(version)) {
			version = GetterUtil.getString(
				attributes.getValue("Bundle-Version"), Version.UNKNOWN);
		}

		if (version.equals(Version.UNKNOWN) && _log.isWarnEnabled()) {
			_log.warn(
				"Plugin package on context " + servletContextName +
					" cannot be tracked because this WAR does not contain a " +
						"liferay-plugin-package.xml file");
		}

And of course, the warning issued is misleading when you look at what we have already found out so far...

[Andrew Jardine, modificado hace 6 años.]

Yes -- fair point. The warning, if I didn't know better, would cause me to actually look into it. It's probably more appropriately logged as an INFO since the result doesn't really have any actual effect on the action.

Experience has led me to ignore the message when it does occur, but I guess if it's your first time seeing it, you could end up wasting time digging into it.