Component Documentation A Brief Roadmap

1
Component Documentation A Brief Roadmap

• RiSEs Seminars
• Eduardo Cruz

2
Component Documentation A Brief Roadmap

• Motivation
• Related work
• UML
• UML Components
• KobrA Project
• RAS
• JSR-170 Content Repository for Java Technology
  API
• Conclusions

3
Motivation Documentation
Component Documentation A Brief Roadmap

• Why is Component Specification important?
• To reuse a complex component, it is necessary to
  understand
• its objectives, its architecture and how to use
  it. Therefore, a
• reusable component should be packaged with all
  the
• documentation necessary to enhance its
  comprehension and
• use.

Monica Ferreira da Silva, Claudia Maria Lima
Werner. "Packaging Reusable Components Using
Patterns and Hypermedia," icsr, vol. 00, no. , p.
146,   1996
4
Motivation Documentation
Component Documentation A Brief Roadmap

• Why is Component Specification important?
• The structure of a repository is key to
  obtaining good retrieval
• results. No matter how intelligent the matching
  algorithm, if
• components are indexed or otherwise structured
  poorly it will
• be difficult to achieve good retrieval
  performance.

S. Henninger, "An Evolutionary Approach to
Constructing Effective Software Reuse
Repositories", ACM Transactions on Software
Engineering and Methodology, 6 (2), ACM, New
York, NY, April 1997, pp. 111-140.
lthttp//citeseer.ist.psu.edu/article/henninger99ev
olutionary.htmlgt
5
Motivation Documentation
Component Documentation A Brief Roadmap

• Why is Component Specification important?
• A Component Specification is typically higher
  level than the
• Component Implementation, and is therefore easier
  to
• understand.
• A Component Specification makes it easier to
  buy, sell, and
• replace components.

http//www-106.ibm.com/developerworks/rational/lib
rary/2883.html
6
Motivation Documentation
Component Documentation A Brief Roadmap

• Why is Component Specification important?
• Component-based software reuse faces an inherent
  dilemma
• in order for the approach to be useful, the
  repository must
• contain enough components to support developers,
  but when
• many examples are available, finding and choosing
  appropriate
• ones becomes troublesome.

S. Henninger, "An Evolutionary Approach to
Constructing Effective Software Reuse
Repositories", ACM Transactions on Software
Engineering and Methodology, 6 (2), ACM, New
York, NY, April 1997, pp. 111-140.
lthttp//citeseer.ist.psu.edu/article/henninger99ev
olutionary.htmlgt
7
Software Documentation
Component Documentation A Brief Roadmap

• Documentation Categories
• Software Documentation
• User Documentation
• System Documentation
• Process Documentation
• Reuse Documentation
• Reuse Manual
• Documentation Reuse
• Documentation Inheritance

J. Sametinger, Software Engineering with Reusable
Components, Springer Verlag, 1997, pp.275
8
UML and UML Components
Component Documentation A Brief Roadmap

• UML
• Great market adoption
• High level abstraction
• Diagrams
• Package Diagram
• Component Diagram

9
UML and UML Components
Component Documentation A Brief Roadmap

• UML Components
• CBD Process
• Better Component Specification
• Sub Components
• Pre and Postconditions (OCL)
• How does one translate the Component
  Specification into a Component Implementation?
• l How does one verify that the Component
  Implementation complies with the Component
  Specification?
• What are the overheads of maintaining both a
  specification model and an implementation model?

http//www-106.ibm.com/developerworks/rational/lib
rary/2883.html
10
Motivation Documentation
Component Documentation A Brief Roadmap

• Why is Component Specification important?
• In general, a lot of focus has been placed on
  software code reuse, but not enough on the other
  parts involved in the software development
  process If we consider each of these items as a
  document, one can abstract the information in
  it

Guerrieri E. Software Document Reuse with XML,"
Proceedings of ICSR-5, pp. 246-254, Victoria, BC,
Canada, June 2-5, 1998
11
XML (eXtensible Markup Language)
Component Documentation A Brief Roadmap

• Document Content Reuse
• Document structure reuse
• Documetn style reuse

Guerrieri E. Software Document Reuse with XML,"
Proceedings of ICSR-5, pp. 246-254, Victoria, BC,
Canada, June 2-5, 1998
12
RAS Reusable Asset Specification
Component Documentation A Brief Roadmap

• Proposed to OMG
• IBM Rational
• Flashline
• LogicLibrary
• Borland
• Componentsource

13
RAS Reusable Asset Specification
Component Documentation A Brief Roadmap

• Asset
• Higher level of abstraction
• Artifact
• Any workproducts from the software development
  lifecycle, such as requirements documents,
  models, source code files, deployment
  descriptors, test cases or scripts, and so on. In
  general the term artifact is associated with a
  file.
• XML Schema and MOF XMI

14
RAS Reusable Asset Specification
Component Documentation A Brief Roadmap

• Granularity
• How many particular problems or solution
  alternatives a packaged asset addresses
• Variability
• asset can be invariable, that is it cannot be
  altered in any significant way black-box
• assets are created with the expectation that
  asset consumers will edit and alter its
  implementation white-box
• Articulation
• Degree of completeness of the artifacts in
  providing the solution. Assets whose artifacts
  specify a solution but do not provide the
  solution have a low degree of articulation.
  Whereas assets whose artifacts specify and
  implement a solution along with supporting
  documents such as requirements, use cases,
  testing artifacts, and so on, have a greater
  degree of articulation

15
RAS Core RAS and Profile
Component Documentation A Brief Roadmap

• Classification
• Descriptors for classifying the asset as well as
  a description of the context(s) for which the
  asset is relevan
• Solution
• Artifacts of the asset.
• Usage
• Rules for installing, customizing, and using the
  asset.
• Related Asset
• Assets relationship to other assets.

16
RAS Compliance
Component Documentation A Brief Roadmap

• Required elements
• Asset
• Profile
• Solution

17
RAS Asset Packaging
Component Documentation A Brief Roadmap

• Bundled
• As Single Archive File
• Unbundled
• With Artifacts In Original Location (CVS)
• Unbundled
• With Artifacts Moved To New Location

18
(No Transcript)
19
JSR-170 Content Repository for Java API
Component Documentation A Brief Roadmap

• Schedule
• Community Draft submitted oct-2003
• Community Review closed dec-2003
• Public Draft submitted may-2004
• Public Review closed jul-2004
• Proposed Final Draft submitted feb-2005
• Final Release may-2005

20
JSR-170 Content Repository for Java API
Component Documentation A Brief Roadmap

• Expert Group
• Apache Software Foundation
• BEA Systems
• Day Software, Inc.
• Fujitsu Limited
• Google Inc (Final Approval Ballot)
• Hewlett-Packard
• IBM
• Macromedia, Inc.
• Novell, Inc.
• Oracle
• SAP
• Sun Microsystems, Inc.
• And others ...

21
JSR-170 Content Repository for Java API
Component Documentation A Brief Roadmap

• Motivation
• Today, (web) applications have to adapt to every
  vendor's proprietary API to interact with content
  repositories. This has the negative effect of
  locking a large percentage of information assets
  in vendor specific formats, limiting access to
  information, impacting system evolution/migration,
  and availability of third party content
  management tools
• There is no easy way to integrate
  content-producer-applications (CMS) and
  content-consumer-applications (CRM,
  Personalization, Portal, etc.) independently of
  the actual underlying content repository
• There exists no Content Repository centric
  standard that appears to address issues such as
  version handling, full-text searching, and
  event-monitoring in a coherent manner

22
JSR-170 Content Repository for Java API
Component Documentation A Brief Roadmap

• Motivation
• Today, (web) applications have to adapt to every
  vendor's proprietary API to interact with content
  repositories. This has the negative effect of
  locking a large percentage of information assets
  in vendor specific formats, limiting access to
  information, impacting system evolution/migration,
  and availability of third party content
  management tools.
• There is no easy way to integrate
  content-producer-applications (CMS) and
  content-consumer-applications (CRM,
  Personalization, Portal, etc.) independently of
  the actual underlying content repository
• Target
• Server-based applications interacting with
  content repositories

23
Reuse Techniques
24
(No Transcript)
25
(No Transcript)
26
The Begin
Component Documentation A Brief Roadmap
27
References
Component Documentation A Brief Roadmap

• J.S. Poulin, "Populating Software Repositories
  Incentives and Domain-Specific Software", The
  Journal of Systems and Software 30(3), Elsevier
  Science, New York, NY, September 1995, pp.
  187-199.
• S. Henninger, "An Evolutionary Approach to
  Constructing Effective Software Reuse
  Repositories", ACM Transactions on Software
  Engineering and Methodology, 6 (2), ACM, New
  York, NY, April 1997, pp. 111-140. Reusable Asset
  Specification
• D. Voth, Packaging Reusable Software Assets,
  Software IEEE, June 2004, pp. 107-108
• M. F. da Silva, C. M. L. Werner, Packaging
  Reusable Components Using Patterns and
  Hypermedia.
• C. Atkinson, J. Bayer, C. Bunse, E. Kamsties, O.
  Laitenberger, R. Laqua, D. Muthig, B. Paech, J.
  Wust, J. Zettel, Component-Based Product Line
  Engineering with UML, Addison-Wesley, 2002, pp.
  503.
• E. Guerrieri, "Software Document Reuse with XML,"
  Proceedings of ICSR-5, pp. 246-254, Victoria, BC,
  Canada, June 2-5, 1998.
• J. Cheesman, J. Daniels, UML Components,
  Addison-Wesley, 2001, pp. 176.
• D. F. D'Souza, A. C. Wills, Objects, Components,
  and Frameworks with UML The Catalysis Approach,
  Addison Wesley, 1998, pp.816
• J. Sametinger, Software Engineering with Reusable
  Components, Springer Verlag, 1997, pp.275