.

.

Info:
The following properties are described inside IDL but not implemented:
- "Generator"
- "Language"
- "Theme"

The following properties are implemented but not described inside IDL:
- "EditingCycles"
- "EditingDuration"
- "SaveVersionOnClose"
- "TemplateFileName"

mba: retargetted due to heavy workload

*** Issue 36387 has been marked as a duplicate of this issue. ***

Someone has changed IDL documentation and implementation from 1.1.4 to 1.9. But the 
result is still inconsistent.

OOo 1.1.4 design 
DocumentInfo.Subject : does not exist 
DocumentInfo.Theme : contains the subject of the document
SDK 1.1.0 
DocumentInfo.Subject : described 
DocumentInfo.Theme : described as Deprecated 

OOo 1.9.113 design 
DocumentInfo.Subject : contains the subject of the document
DocumentInfo.Theme : *does not exist*
SDK 1.9.113 
DocumentInfo.Subject : described as Deprecated 
DocumentInfo.Theme : described

These changes are not acceptable when you work with the API because implementation is 
changed from 1.1 to 1.9. Theme should still contain the Subject information.

As of OOo 2.1, the difference between the documentation
http://api.openoffice.org/docs/common/ref/com/sun/star/document/DocumentInfo.html

And what is retrieved is as follows:

Listed in Documentation, but not part of implementation:
  * Generator
  * Language
  * Theme

Properties returned by Implementation, but not listed in documentation:
  * CharLocale
  * DocumentStatistic
  * EditingCycles
  * EditingDuration
  * SaveVersionOnClose
  * TemplateFileName

However, CharLocale and DocumentStatistic both return a void object instead of a
Locale struct for the CharLocale or anything useful for the DocumentStatistic

ModifyDate (if not yet saved) & PrintDate (until printed) return void objects as
well

IsEncrypted is documented as boolean (& deprecated), but returned as empty string

The target of this issue should be reconsidered IMHO - at least the
documentation should be updated accordingly.

taking over

Thanks for the helpful comments.

I think that both implementation as well as documentation need a fix. So I
invested some time thinking about reasonable content of DocumentInfo. Please
keep in mind that service documentation of "old style" services never was
anything more than documentation, no code was generated from it and changes will
not create technically incompatibilities. A consistent definition of the
DocumentInfo service should be important. 

First I would like to convert the DocumentInfo service into a "new style"
service with a multiple inheritance interface. Properties will stay properties
but additionally will be available as attributes and so it becomes even more
important to decide which properties/attributes we want to have here. I already
started a complete code refactoring of the implementation of the DocumentInfo
services in sfx2 and the corresponding SfxDocumentInfo class. Goal of the
refactoring was that the service should be usable without the execution of any
SFX based code.

(1) "Theme" vs. "Subject"

Though "Subject" is marked as deprecated I like it more than "Theme". As our
implementation of OOo2.x always supported the first and not the second one it
should be safe to remove the deprecation from "Subject" and remove "Theme"
completely. For compatibility reasons to some 1.x versions that supported
"Theme" (as mentioned by bmarcelly) we could support "Theme" to not break any
code using it but don't document it. OTOH I doubt that this is necessary as code
using "Theme" now is broken at least since OOo2.0. bmarcelly, please comment.

(2) Old deprecated properties related to mail/news ("CC" etc.)

All these properties have never been returned anything useful and so I would
like to remove them completely. 

(3) "Language" vs. "CharLocale"

"CharLocale" will be renamed to "Language". I will fix the bug that it currently
is supported only for the standalone case.

(4) "DocumentStatistics"

This property is necessary and so it will become documented. I will fix the bug
that it currently is supported only for the standalone case.

(5) "EditingCycles", "EditingDuration"

These properties are necessary and so they will become documented.

(6) "SaveVersionOnClose"

This property is not part of the OOo metadata, it is stored in settings.xml. For
historical reason it was part of our DocumentInfo but I'm not sure if that was a
good idea. As it is not documented anyway I tend to remove it and place it into
another object.

(7) "TemplateFileName"

The role of this property is somewhat unclear. Currently it is necessary as the
more understandable "Template" property is applied for updates only in case
"TemplateFileName" is set also. This must be some legay code. In very old
versions of StarOffice "TemplateFileName" was also used in case "Template" was
not set, thus enabling updates from templates that are not part of the templates
component. Before we can decide how to go on with "TemplateFileName" we must
clarify how we want to treat updates from templates in the future. I will start
a discussion around this pretty soon.

(8) Empty DateTime properties

If dates are not set (as the file hasn't been printed or saved or in case the
user opted against storing personal data) returning "void" properties looks like
a good way to express this. Or can we take a particular value for
css.util.DateTime as an "invalid" value?

(9) IsEncrypted return string values

I didn't try to reproduce this but I can say that the refactored code does
handle this property correctly. I'm currently thinking whether it can be removed
also as it seems that currently nobody uses it and the information is available
through the documents' MediaDescriptor (xModel->getArgs()) anyway. 

Some words about the interface design.
According to the documentation each DocumentInfo object must be disposed. This
seems to be due to historical implementation details as the
StandaloneDocumentInfo held some SFX based resources. After my refactoring this
isn't true anymore and such an object can live as long as it does without
problems. So disposing it isn't necessary. As current code might do that I think
we should keep the interface for the StandaloneDocumentInfo. Disposing a "not
standalone" DocumentInfo was a bug anyway (as only the document as its owner is
allowed to do so) and so we can make it an optional interface here. Details will
follow on interface.discuss.

Now documentation and implementation are in-sync
Here's what was done:

(1) "Theme" is removed, "Subject" not deprecated anymore
(2) Mail properties that wheren't documented are now also removed from
implementation (haven't been used anyway)
(3) "Language" now is supported in all cases; it is currently not set by OOo
itself as this would be a bigger change that touches more code than just
DocumentInfo.
(4) DocumentStatistics now is supported; we still need documentation about what
properties are available. As this is application dependant we need to find a
place for this.
(5) EditingCycles and EditingDuration are now documented
(6) SaveVersionOnClose has been moved to the DocumentSettings Service; it is
stored in settings.xml anyway
(7) TemplateFileName is still open, nothing changed
(8) The whole office code has been reviewed to deal with invalid DateTime
objects properly; the OLE value is now used only in binfilter and MS filters
(9) IsEncrypted has been removed as it only was needed for binary files and
wasn't used anyway

Nothing was changed wrt. the interfaces and services. This will happen later.

Please verify that the supported properties now match the documentation

cn: PING!
Please verify

ok in cws basemodelrefactoring => verified

ok in master => close