liferay-docs
liferay-docs copied to clipboard
Correct inaccuracies and wording
The following changes are included in this commit. I realize this is 6.2.x documentation, but this is the only official publication that speaks directly to Service Builder's generated classes and it is applicable in all portals from 6.0 to DXP. Two of the corrections made are for fairly serious factual inaccuracies. Evidence to support my claim is added at the bottom.
- The word "customize" and "customizable" were used in this document in reference to generated classes that allowed direct modification by the developer. This is inconsistent with the JavaDocs and block comments in the portal's source code. Every reference I have seen to these classes has used the words "modify" and "modifiable". I have changed them in this document where applicable.
- Previously this document listed three generate classes that are directly modifiable: *LocalServiceImpl, *ServiceImpl, *ModelImpl. The first two in the list are correct. However, *ModelImpl is not, in any portal release, directly modifiable. The original author was attempting to state that an entity model is modifiable. However, to modify an entity model you do NOT modify *ModelImpl, you modify EntityImpl where Entity is the name of any entity specified in Service Builder. I had to restructure how this was stated, because following the previous structure I would have to say that *Impl classes are modifiable which is false. Not all *Impl classes are modifiable. Only the two service impl's and the EntityImpl.
- Figure 4 said that Only EventImpl allows custom methods to be added to the service layer. This is incorrect. Only EventImpl allows "custom methods" to be added to the model layer. So I switched the word service with the word model, and I also reworded it to use "modification" over custom.
Comments for a ModelImpl
/*
* NOTE FOR DEVELOPERS:
*
* Never modify or reference this class directly. All methods that expect a message model instance should use the {@link Message} interface instead.
*/
Comments for a EntityImpl
/*
* NOTE FOR DEVELOPERS:
*
* Never reference this class directly. All methods that expect a order model instance should use the {@link com.latham.inquiry.model.Order} interface instead.
*/
This morning I realized that there is obviously a copy of this file in the master branch as well. I verified that the same issues are present in the master branch. I modified that file similarly (but slightly differently due to other modifications that were present) and submitted a pull request. I'm not sure how merging between the two branches is done internally, or what the procedure for something like this is,
However if 6.2.x docs are ever merged with master or visa versa I would favor the pull request on the master branch over this one. The master pull request follows a better naming convention that exists in the master but doesn't exist in the 6.2.x branch