Re: svn commit: r981018 - in /ofbiz/trunk/framework/service
Locked
Re: svn commit: r981018 - in /ofbiz/trunk/framework/service
 
|
Re: svn commit: r981018 - in /ofbiz/trunk/framework/service
|
|
Re: svn commit: r981018 - in /ofbiz/trunk/framework/service
|
|
Yeah whoops, thanks for fixing that up.
Inline Regards Scott On 1/08/2010, at 3:55 AM, Adrian Crum wrote: > Scott, > > I fixed the code and built it out a little. > > This is a good idea, but I have a couple of problems with it: > > 1. User-oriented meta-data should be kept in properties files - so it can be internationalized. The drawback to that is, developers will be less likely to include descriptions if they have to do it in a separate file. It wasn't my intention for the meta-data to be oriented towards the user, I see it as developer documentation only. A few times in the past I've noticed it can be difficult to describe an attributes purpose from the service description and inlining them was intended to make it a little more like a javadoc. > 2. Description text should not be stored in the model - it increases the model's memory footprint greatly. Instead, the descriptions should be retrieved from properties files when needed (in AvailableServices.groovy, for example). Well I agree with you except for the properties file part, but I guess that comes back to #1 above. We could always look at doing some sort of lazy loading, where the descriptions are only added to the model if they're requested. Considering that viewing the service in webtools is the only way to expose the descriptions, you'd probably never end up with more than a few dozen actually loaded into memory. > > -Adrian > > > --- On Sat, 7/31/10, Adrian Crum <[hidden email]> wrote: >> Scott, >> >> Are you sure this does what you intended? The parameters >> are being assigned the service's description, not the >> parameter's description. >> >> -Adrian >> >> --- On Sat, 7/31/10, [hidden email] >> <[hidden email]> >> wrote: >> >>> From: [hidden email] >> <[hidden email]> >>> Subject: svn commit: r981018 - in >> /ofbiz/trunk/framework/service: dtd/services.xsd >> src/org/ofbiz/service/ModelParam.java >> src/org/ofbiz/service/ModelServiceReader.java >>> To: [hidden email] >>> Date: Saturday, July 31, 2010, 1:26 AM >>> Author: lektran >>> Date: Sat Jul 31 08:26:42 2010 >>> New Revision: 981018 >>> >>> URL: http://svn.apache.org/viewvc?rev=981018&view=rev >>> Log: >>> Add a description element for service attributes, >> should >>> make documenting some services a little easier. >> Still >>> need to display it in webtools somewhere. >>> >>> Modified: >>> >>> ofbiz/trunk/framework/service/dtd/services.xsd >>> >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>> >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>> >>> Modified: >> ofbiz/trunk/framework/service/dtd/services.xsd >>> URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/dtd/services.xsd?rev=981018&r1=981017&r2=981018&view=diff >>> >> ============================================================================== >>> --- ofbiz/trunk/framework/service/dtd/services.xsd >>> (original) >>> +++ ofbiz/trunk/framework/service/dtd/services.xsd Sat >> Jul >>> 31 08:26:42 2010 >>> @@ -314,6 +314,7 @@ under the License. >>> >>> <xs:complexType> >>> >>> <xs:sequence> >>> >>> <xs:element minOccurs="0" >>> maxOccurs="unbounded" ref="type-validate"/> >>> + >>> <xs:element minOccurs="0" ref="description" /> >>> >>> </xs:sequence> >>> >>> <xs:attributeGroup >>> ref="attlist.attribute"/> >>> >>> </xs:complexType> >>> >>> Modified: >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>> URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java?rev=981018&r1=981017&r2=981018&view=diff >>> >> ============================================================================== >>> --- >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>> (original) >>> +++ >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>> Sat Jul 31 08:26:42 2010 >>> @@ -43,6 +43,9 @@ public class ModelParam implements >> Seria >>> /** Parameter name */ >>> public String name; >>> >>> + /** The description of this parameter */ >>> + public String description; >>> + >>> /** Paramater type */ >>> public String type; >>> >>> @@ -88,6 +91,7 @@ public class ModelParam implements >> Seria >>> >>> public ModelParam(ModelParam >>> param) { >>> this.name = >>> param.name; >>> + this.description = >>> param.description; >>> this.type = >>> param.type; >>> this.mode = >>> param.mode; >>> this.formLabel = >>> param.formLabel; >>> >>> Modified: >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>> URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java?rev=981018&r1=981017&r2=981018&view=diff >>> >> ============================================================================== >>> --- >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>> (original) >>> +++ >>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>> Sat Jul 31 08:26:42 2010 >>> @@ -518,6 +518,7 @@ public class ModelServiceReader >>> implemen >>> >>> ModelParam param = new ModelParam(); >>> >>> >>> param.name = >>> >> UtilXml.checkEmpty(attribute.getAttribute("name")).intern(); >>> + >>> param.description = getCDATADef(baseElement, >>> "description"); >>> >>> param.type = >>> >> UtilXml.checkEmpty(attribute.getAttribute("type")).intern(); >>> >>> param.mode = >>> >> UtilXml.checkEmpty(attribute.getAttribute("mode")).intern(); >>> >>> param.entityName = >>> >> UtilXml.checkEmpty(attribute.getAttribute("entity-name")).intern(); >>> >>> >>> >> >> >> >> > > > |
smime.p7s (3K)
Re: svn commit: r981018 - in /ofbiz/trunk/framework/service
|
|
Re: svn commit: r981018 - in /ofbiz/trunk/framework/service
|
|
On 1/08/2010, at 11:24 AM, Adrian Crum wrote:
> --- On Sat, 7/31/10, Scott Gray <[hidden email]> wrote: >> Yeah whoops, thanks for fixing that >> up. >> >> Inline >> >> Regards >> Scott >> >> On 1/08/2010, at 3:55 AM, Adrian Crum wrote: >> >>> Scott, >>> >>> I fixed the code and built it out a little. >>> >>> This is a good idea, but I have a couple of problems >> with it: >>> >>> 1. User-oriented meta-data should be kept in >> properties files - so it can be internationalized. The >> drawback to that is, developers will be less likely to >> include descriptions if they have to do it in a separate >> file. >> >> It wasn't my intention for the meta-data to be oriented >> towards the user, I see it as developer documentation >> only. A few times in the past I've noticed it can be >> difficult to describe an attributes purpose from the service >> description and inlining them was intended to make it a >> little more like a javadoc. > > By user I meant developer. If it's developer information only, then why store it in the model? A developer could just look at the service definition file. >>> 2. Description text should not be stored in the model >> - it increases the model's memory footprint greatly. >> Instead, the descriptions should be retrieved from >> properties files when needed (in AvailableServices.groovy, >> for example). >> >> Well I agree with you except for the properties file part, >> but I guess that comes back to #1 above. We could >> always look at doing some sort of lazy loading, where the >> descriptions are only added to the model if they're >> requested. Considering that viewing the service in >> webtools is the only way to expose the descriptions, you'd >> probably never end up with more than a few dozen actually >> loaded into memory. > > The reason I suggested the properties file is because this issue came up before with the entity field descriptions. At the time those were being added, there was interest in internationalizing them. > From my perspective, using a properties file is easier than the existing implementation. In the AvailableServices.groovy script, concatenate the service name and attribute name, then use that as a key to look up the description in a properties file. No need to add anything to the model. I don't think we are so good at documentation that we should be okay with making it any harder :-) >>> >>> -Adrian >>> >>> >>> --- On Sat, 7/31/10, Adrian Crum <[hidden email]> >> wrote: >>>> Scott, >>>> >>>> Are you sure this does what you intended? The >> parameters >>>> are being assigned the service's description, not >> the >>>> parameter's description. >>>> >>>> -Adrian >>>> >>>> --- On Sat, 7/31/10, [hidden email] >>>> <[hidden email]> >>>> wrote: >>>> >>>>> From: [hidden email] >>>> <[hidden email]> >>>>> Subject: svn commit: r981018 - in >>>> /ofbiz/trunk/framework/service: dtd/services.xsd >>>> src/org/ofbiz/service/ModelParam.java >>>> src/org/ofbiz/service/ModelServiceReader.java >>>>> To: [hidden email] >>>>> Date: Saturday, July 31, 2010, 1:26 AM >>>>> Author: lektran >>>>> Date: Sat Jul 31 08:26:42 2010 >>>>> New Revision: 981018 >>>>> >>>>> URL: http://svn.apache.org/viewvc?rev=981018&view=rev >>>>> Log: >>>>> Add a description element for service >> attributes, >>>> should >>>>> make documenting some services a little >> easier. >>>> Still >>>>> need to display it in webtools somewhere. >>>>> >>>>> Modified: >>>>> >>>>> >> ofbiz/trunk/framework/service/dtd/services.xsd >>>>> >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>>>> >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>>>> >>>>> Modified: >>>> ofbiz/trunk/framework/service/dtd/services.xsd >>>>> URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/dtd/services.xsd?rev=981018&r1=981017&r2=981018&view=diff >>>>> >>>> >> ============================================================================== >>>>> --- >> ofbiz/trunk/framework/service/dtd/services.xsd >>>>> (original) >>>>> +++ >> ofbiz/trunk/framework/service/dtd/services.xsd Sat >>>> Jul >>>>> 31 08:26:42 2010 >>>>> @@ -314,6 +314,7 @@ under the License. >>>>> >>>>> <xs:complexType> >>>>> >>>>> <xs:sequence> >>>>> >> >>>>> <xs:element minOccurs="0" >>>>> maxOccurs="unbounded" >> ref="type-validate"/> >>>>> + >> >>>>> <xs:element minOccurs="0" ref="description" >> /> >>>>> >>>>> </xs:sequence> >>>>> >>>>> <xs:attributeGroup >>>>> ref="attlist.attribute"/> > >>>>> >>>>> </xs:complexType> >>>>> >>>>> Modified: >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>>>> URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java?rev=981018&r1=981017&r2=981018&view=diff >>>>> >>>> >> ============================================================================== >>>>> --- >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>>>> (original) >>>>> +++ >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelParam.java >>>>> Sat Jul 31 08:26:42 2010 >>>>> @@ -43,6 +43,9 @@ public class ModelParam >> implements >>>> Seria >>>>> /** Parameter name */ >>>>> public String name; >>>>> >>>>> + /** The description of this >> parameter */ >>>>> + public String description; >>>>> + >>>>> /** Paramater type */ >>>>> public String type; >>>>> >>>>> @@ -88,6 +91,7 @@ public class ModelParam >> implements >>>> Seria >>>>> >>>>> public >> ModelParam(ModelParam >>>>> param) { >>>>> this.name = >>>>> param.name; >>>>> + this.description >> = >>>>> param.description; >>>>> this.type = >>>>> param.type; >>>>> this.mode = >>>>> param.mode; >>>>> >> this.formLabel = >>>>> param.formLabel; >>>>> >>>>> Modified: >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>>>> URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java?rev=981018&r1=981017&r2=981018&view=diff >>>>> >>>> >> ============================================================================== >>>>> --- >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>>>> (original) >>>>> +++ >>>>> >>>> >> ofbiz/trunk/framework/service/src/org/ofbiz/service/ModelServiceReader.java >>>>> Sat Jul 31 08:26:42 2010 >>>>> @@ -518,6 +518,7 @@ public class >> ModelServiceReader >>>>> implemen >>>>> >>>>> ModelParam param = new >> ModelParam(); >>>>> >>>>> >>>>> param.name = >>>>> >>>> >> UtilXml.checkEmpty(attribute.getAttribute("name")).intern(); >>>>> + >> >>>>> param.description = getCDATADef(baseElement, >>>>> "description"); >>>>> >>>>> param.type = >>>>> >>>> >> UtilXml.checkEmpty(attribute.getAttribute("type")).intern(); >>>>> >>>>> param.mode = >>>>> >>>> >> UtilXml.checkEmpty(attribute.getAttribute("mode")).intern(); >>>>> >>>>> param.entityName = >>>>> >>>> >> UtilXml.checkEmpty(attribute.getAttribute("entity-name")).intern(); >>>>> >>>>> >>>>> >>>> >>>> >>>> >>>> >>> >>> >>> >> >> > > > |
Re: svn commit: r981018 - in /ofbiz/trunk/framework/service
Administrator
|
| Free forum by Nabble | Edit this page |