Re: Documentation should link to Jackrabbit API
Great, worked like a charm: https://jackrabbit.apache.org/oak/docs/index.html Cheers, Alex > On 09.08.2018, at 11:10, Marcel Reutegger wrote: > > On 09.08.18, 01:46, "Alexander Klimetschek" wrote: >> To deploy this doc site change, IIUC, I would first commit the change, then >> do "mvn site-deploy -Pdoc" from within the svn checkout? > > Yes, see also oak-doc/README.md > > Regards > Marcel >
[jira] [Commented] (JCR-4355) Javadoc fixes and improvements for new direct binary access API
[
https://issues.apache.org/jira/browse/JCR-4355?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16576874#comment-16576874
]
Alexander Klimetschek commented on JCR-4355:
Thanks for the review. It would actually be nice to have a github workflow to
view and discuss these changes...
{quote}charset issue
{quote}
Ok to use _if the media type defines a "charset"_ in all places? (Your patch
just adapted one)
{quote}reduces the amount of @link tags having in-line prose (which I find
confusing to read)
{quote}
I used them (with just the method name w/o classname and parameters) to
increase readability in the final rendered HTML, otherwise there are repeated
very long {{JackrabbitValueFactory.somelongmethod(with, many, params)}} in
there. Wanted the docs be optimized for their html reading, not the java
sources.
Note in at least one place, your changes reformatted lists to an inline
text block (probably IDE reformatting), making them hard to follow in the
sources.
+1 for the direct link to upload algorithm.
{quote}Some storage providers also support multi-part uploads by reusing a
single URI multiple times, in which case the implementation may also return a
single URI regardless of the size of the data being uploaded
{quote}
I did not touch that text. This refers to Google Cloud Storage, which is the
only one of the major providers (AWS, Azure, Rackspace, Google) to support
[multipart via standard Content-Range headers on
PUT|https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload],
without requiring separate part URLs. Which would be more standards-compliant
and simplifies the whole approach to a single URL, but, well... Anyway, we
don't support Google as DataStore right now, so there is no end-to-end
integration of that approach, nor is there a description of that in the upload
algorithm.
If we would add this, with the current API, a client could potentially detect
this case if getMaxPartSize() is smaller than the original file size AND a
single URI is provided. But I fear that might be a bit too fragile, and we
probably need a flag for that in the BinaryUpload instructions, such as
{{canUseContentRange()}}.
Maybe for now it's best to take that out of the javadoc, and only add this in
the future, when needed and it's clear how it can work.
I'll work on a new iteration of the docs.
> Javadoc fixes and improvements for new direct binary access API
> ---
>
> Key: JCR-4355
> URL: https://issues.apache.org/jira/browse/JCR-4355
> Project: Jackrabbit Content Repository
> Issue Type: Improvement
> Components: jackrabbit-api
>Reporter: Alexander Klimetschek
>Priority: Major
> Fix For: 2.18
>
> Attachments: JCR-4355-jr.diff, JCR-4355-v2-javadoc-html.zip,
> JCR-4355-v2.patch, JCR-4355.diff
>
>
> Here are some changes to the javadocs for the new API:
> [OAK-7569-api-javadoc-improvements.patch|https://issues.apache.org/jira/secure/attachment/12934364/12934364_OAK-7569-api-javadoc-improvements.patch]
> * more concise descriptions
> * correcting some inaccuracies (clients cannot choose whether to do single or
> multipart upload, multipart might be strictly required depending on the size)
> * most importantly the upload algorithm (standard partSize calculation was
> wrong)
> * focus on API users, separated notes to implementors
> * for BinaryDownloadOptions added note from which jcr properties a client
> would normally take these values from
> * added security considerations
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Created] (JCRVLT-316) Add dedicated parameter to specify subPackageHandling
Konrad Windszus created JCRVLT-316:
--
Summary: Add dedicated parameter to specify subPackageHandling
Key: JCRVLT-316
URL: https://issues.apache.org/jira/browse/JCRVLT-316
Project: Jackrabbit FileVault
Issue Type: Improvement
Components: package maven plugin
Affects Versions: package-maven-plugin-1.0.1
Reporter: Konrad Windszus
Fix For: package-maven-plugin-1.0.2
Currently the {{subPackageHandling}} need to be specified as string value below
the {{properties}} parameter. Similar to the {{accessControlHandling}} there
should be a strongly typed parameter for that.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Updated] (JCRVLT-315) Improve error message in case of embedding invalid sub packages
[
https://issues.apache.org/jira/browse/JCRVLT-315?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Konrad Windszus updated JCRVLT-315:
---
Status: Patch Available (was: Open)
> Improve error message in case of embedding invalid sub packages
> ---
>
> Key: JCRVLT-315
> URL: https://issues.apache.org/jira/browse/JCRVLT-315
> Project: Jackrabbit FileVault
> Issue Type: Improvement
> Components: package maven plugin
>Affects Versions: package-maven-plugin-1.0.1
>Reporter: Konrad Windszus
>Priority: Major
> Fix For: package-maven-plugin-1.0.2
>
>
> Currently the error message being emitted for invalid ZIP files referenced as
> sub packages is pretty confusing. It is lacking the original ZIP file name.
> An example error message looks like this
> {code}
> [INFO] --- filevault-package-maven-plugin:1.0.2-SNAPSHOT:generate-metadata
> (default-generate-metadata) @ completepackage ---
> [INFO] Embedding --- Sub Packages:
> groupId=,artifactId=,type=zip,classifier=,filter=true,excludeTransitive=false
> ---
> [INFO]
>
> [INFO] BUILD FAILURE
> [INFO]
>
> [INFO] Total time: 2.061 s
> [INFO] Finished at: 2018-08-10T16:35:09+02:00
> [INFO]
>
> [ERROR] Failed to execute goal
> org.apache.jackrabbit:filevault-package-maven-plugin:1.0.2-SNAPSHOT:generate-metadata
> (default-generate-metadata) on project completepackage:
> java.util.zip.ZipException: zip file is empty -> [Help 1]
> {code}
> It is completely lacking the source file name of the sub package which was
> supposed to be embedded.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Created] (JCRVLT-315) Improve error message in case of embedding invalid sub packages
Konrad Windszus created JCRVLT-315:
--
Summary: Improve error message in case of embedding invalid sub
packages
Key: JCRVLT-315
URL: https://issues.apache.org/jira/browse/JCRVLT-315
Project: Jackrabbit FileVault
Issue Type: Improvement
Components: package maven plugin
Affects Versions: package-maven-plugin-1.0.1
Reporter: Konrad Windszus
Fix For: package-maven-plugin-1.0.2
Currently the error message being emitted for invalid ZIP files referenced as
sub packages is pretty confusing. It is lacking the original ZIP file name.
An example error message looks like this
{code}
[INFO] --- filevault-package-maven-plugin:1.0.2-SNAPSHOT:generate-metadata
(default-generate-metadata) @ completepackage ---
[INFO] Embedding --- Sub Packages:
groupId=,artifactId=,type=zip,classifier=,filter=true,excludeTransitive=false
---
[INFO]
[INFO] BUILD FAILURE
[INFO]
[INFO] Total time: 2.061 s
[INFO] Finished at: 2018-08-10T16:35:09+02:00
[INFO]
[ERROR] Failed to execute goal
org.apache.jackrabbit:filevault-package-maven-plugin:1.0.2-SNAPSHOT:generate-metadata
(default-generate-metadata) on project completepackage:
java.util.zip.ZipException: zip file is empty -> [Help 1]
{code}
It is completely lacking the source file name of the sub package which was
supposed to be embedded.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Commented] (JCRVLT-288) Support XML Docview formatting in a dedicated goal
[
https://issues.apache.org/jira/browse/JCRVLT-288?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16576322#comment-16576322
]
Konrad Windszus commented on JCRVLT-288:
After upgrading the PR
https://github.com/apache/jackrabbit-filevault-package-maven-plugin/pull/15 to
the FileVault 3.2.0 (release version) I get the following failures in some ITs
{code}
[INFO] Running org.apache.jackrabbit.filevault.maven.packaging.it.FilterIT
[ERROR] Tests run: 13, Failures: 2, Errors: 0, Skipped: 0, Time elapsed: 59.063
s <<< FAILURE! - in org.apache.jackrabbit.filevault.maven.packaging.it.FilterIT
[ERROR]
test_merge_inline_filter_with_metainf(org.apache.jackrabbit.filevault.maven.packaging.it.FilterIT)
Time elapsed: 7.496 s <<< FAILURE!
org.junit.ComparisonFailure:
filter.xml is correct expected:<...
https://issues.apache.org/jira/browse/JCRVLT-288
> Project: Jackrabbit FileVault
> Issue Type: Improvement
> Components: package maven plugin
>Affects Versions: package-maven-plugin-1.0.1
>Reporter: Konrad Windszus
>Priority: Major
> Fix For: package-maven-plugin-1.0.2
>
>
> There should be a dedicated goal which either formats XML files according to
> the Jackrabbit Filevault Docview XML format or only check if files are
> compliant with that format (e.g. for CI servers). The goal should support m2e
> properly (i.e. support emitting error messages or reformatting source files
> in an incremental build)
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Commented] (JCR-4354) VFS (commons-vfs) based FileSystem for VFS backend based Persistence Manager
[
https://issues.apache.org/jira/browse/JCR-4354?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16576319#comment-16576319
]
Julian Reschke commented on JCR-4354:
-
SVN patch with two Javadoc fixes: [^JCR-4354.diff]
Tests pass, feedback from committers with more Jackrabbit FS experience
appreciated...
> VFS (commons-vfs) based FileSystem for VFS backend based Persistence Manager
>
>
> Key: JCR-4354
> URL: https://issues.apache.org/jira/browse/JCR-4354
> Project: Jackrabbit Content Repository
> Issue Type: Improvement
>Reporter: Woonsan Ko
>Priority: Major
> Labels: PatchAvailable
> Fix For: 2.18, 2.17.6
>
> Attachments: JCR-4354.diff
>
>
> I think it would be nice to have a VFS (commons-vfs) based {{FileSystem}}
> which then can be used by {{BundleFsPersistenceManager}}.
> For example, I have worked with a Jackrabbit based WCMS product which
> recommends using one of {{BundleDbPersistenceManager}} components for both
> workspaces and version, which makes it easier for clustering.
> One typical problem is that the version storage in DBMS keeps increasing, so
> as a result we've recommended cleaning up older version items periodically.
> (You may google "cms version cleaner" for more info.)
> In this case, if they were able to configure a VFS based {{FileSystem}} and
> the generic {{PersistenceManager}}, {{BundleFsPersistenceManager}}, for the
> versions, their DB size would keep small enough, and they may keep the
> version items almost infinitely. Actually versioning are used relatively less
> than other normal functionalities such as content retrieval and searching,
> only when authoring users publish a document in our case. So, keeping version
> data separately from database wouldn't be a problem, as long as it supports
> easier clustering (through WebDAV or SFTP in this option).
> Another possible use case is that some people may use VFS based solution for
> both workspaces and version, backed by a clustered WebDAV server or SFTP
> server. They can use VFS-based DataStore provided by JCR-3975 as well. This
> would increase architectural options around Jackrabbit ecosystem.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Updated] (JCR-4354) VFS (commons-vfs) based FileSystem for VFS backend based Persistence Manager
[
https://issues.apache.org/jira/browse/JCR-4354?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Julian Reschke updated JCR-4354:
Attachment: JCR-4354.diff
> VFS (commons-vfs) based FileSystem for VFS backend based Persistence Manager
>
>
> Key: JCR-4354
> URL: https://issues.apache.org/jira/browse/JCR-4354
> Project: Jackrabbit Content Repository
> Issue Type: Improvement
>Reporter: Woonsan Ko
>Priority: Major
> Labels: PatchAvailable
> Fix For: 2.18, 2.17.6
>
> Attachments: JCR-4354.diff
>
>
> I think it would be nice to have a VFS (commons-vfs) based {{FileSystem}}
> which then can be used by {{BundleFsPersistenceManager}}.
> For example, I have worked with a Jackrabbit based WCMS product which
> recommends using one of {{BundleDbPersistenceManager}} components for both
> workspaces and version, which makes it easier for clustering.
> One typical problem is that the version storage in DBMS keeps increasing, so
> as a result we've recommended cleaning up older version items periodically.
> (You may google "cms version cleaner" for more info.)
> In this case, if they were able to configure a VFS based {{FileSystem}} and
> the generic {{PersistenceManager}}, {{BundleFsPersistenceManager}}, for the
> versions, their DB size would keep small enough, and they may keep the
> version items almost infinitely. Actually versioning are used relatively less
> than other normal functionalities such as content retrieval and searching,
> only when authoring users publish a document in our case. So, keeping version
> data separately from database wouldn't be a problem, as long as it supports
> easier clustering (through WebDAV or SFTP in this option).
> Another possible use case is that some people may use VFS based solution for
> both workspaces and version, backed by a clustered WebDAV server or SFTP
> server. They can use VFS-based DataStore provided by JCR-3975 as well. This
> would increase architectural options around Jackrabbit ecosystem.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Assigned] (JCR-4355) Javadoc fixes and improvements for new direct binary access API
[ https://issues.apache.org/jira/browse/JCR-4355?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Julian Reschke reassigned JCR-4355: --- Assignee: (was: Julian Reschke) > Javadoc fixes and improvements for new direct binary access API > --- > > Key: JCR-4355 > URL: https://issues.apache.org/jira/browse/JCR-4355 > Project: Jackrabbit Content Repository > Issue Type: Improvement > Components: jackrabbit-api >Reporter: Alexander Klimetschek >Priority: Major > Fix For: 2.18 > > Attachments: JCR-4355-jr.diff, JCR-4355-v2-javadoc-html.zip, > JCR-4355-v2.patch, JCR-4355.diff > > > Here are some changes to the javadocs for the new API: > [OAK-7569-api-javadoc-improvements.patch|https://issues.apache.org/jira/secure/attachment/12934364/12934364_OAK-7569-api-javadoc-improvements.patch] > * more concise descriptions > * correcting some inaccuracies (clients cannot choose whether to do single or > multipart upload, multipart might be strictly required depending on the size) > * most importantly the upload algorithm (standard partSize calculation was > wrong) > * focus on API users, separated notes to implementors > * for BinaryDownloadOptions added note from which jcr properties a client > would normally take these values from > * added security considerations -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Commented] (JCR-4355) Javadoc fixes and improvements for new direct binary access API
[ https://issues.apache.org/jira/browse/JCR-4355?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16576173#comment-16576173 ] Julian Reschke commented on JCR-4355: - Question about "Some storage providers also support multi-part uploads by reusing a single URI multiple times, in which case the implementation may also return a single URI regardless of the size of the data being uploaded.": How is this supposed to work? What is a client supposed to do here? Is the assumption that the client has builtin-knowledge about the behavior of specific providers? > Javadoc fixes and improvements for new direct binary access API > --- > > Key: JCR-4355 > URL: https://issues.apache.org/jira/browse/JCR-4355 > Project: Jackrabbit Content Repository > Issue Type: Improvement > Components: jackrabbit-api >Reporter: Alexander Klimetschek >Assignee: Julian Reschke >Priority: Major > Fix For: 2.18 > > Attachments: JCR-4355-jr.diff, JCR-4355-v2-javadoc-html.zip, > JCR-4355-v2.patch, JCR-4355.diff > > > Here are some changes to the javadocs for the new API: > [OAK-7569-api-javadoc-improvements.patch|https://issues.apache.org/jira/secure/attachment/12934364/12934364_OAK-7569-api-javadoc-improvements.patch] > * more concise descriptions > * correcting some inaccuracies (clients cannot choose whether to do single or > multipart upload, multipart might be strictly required depending on the size) > * most importantly the upload algorithm (standard partSize calculation was > wrong) > * focus on API users, separated notes to implementors > * for BinaryDownloadOptions added note from which jcr properties a client > would normally take these values from > * added security considerations -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Commented] (JCR-4355) Javadoc fixes and improvements for new direct binary access API
[ https://issues.apache.org/jira/browse/JCR-4355?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16576167#comment-16576167 ] Julian Reschke commented on JCR-4355: - [^JCR-4355-jr.diff] * attempts to clarify the charset issue * reduces the amount of @link tags having in-line prose (which I find confusing to read) * moves the note about non-http URIs to a more generic place * improves linking to "upload algorithm" > Javadoc fixes and improvements for new direct binary access API > --- > > Key: JCR-4355 > URL: https://issues.apache.org/jira/browse/JCR-4355 > Project: Jackrabbit Content Repository > Issue Type: Improvement > Components: jackrabbit-api >Reporter: Alexander Klimetschek >Assignee: Julian Reschke >Priority: Major > Fix For: 2.18 > > Attachments: JCR-4355-jr.diff, JCR-4355-v2-javadoc-html.zip, > JCR-4355-v2.patch, JCR-4355.diff > > > Here are some changes to the javadocs for the new API: > [OAK-7569-api-javadoc-improvements.patch|https://issues.apache.org/jira/secure/attachment/12934364/12934364_OAK-7569-api-javadoc-improvements.patch] > * more concise descriptions > * correcting some inaccuracies (clients cannot choose whether to do single or > multipart upload, multipart might be strictly required depending on the size) > * most importantly the upload algorithm (standard partSize calculation was > wrong) > * focus on API users, separated notes to implementors > * for BinaryDownloadOptions added note from which jcr properties a client > would normally take these values from > * added security considerations -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Updated] (JCR-4355) Javadoc fixes and improvements for new direct binary access API
[ https://issues.apache.org/jira/browse/JCR-4355?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Julian Reschke updated JCR-4355: Attachment: JCR-4355-jr.diff > Javadoc fixes and improvements for new direct binary access API > --- > > Key: JCR-4355 > URL: https://issues.apache.org/jira/browse/JCR-4355 > Project: Jackrabbit Content Repository > Issue Type: Improvement > Components: jackrabbit-api >Reporter: Alexander Klimetschek >Assignee: Julian Reschke >Priority: Major > Fix For: 2.18 > > Attachments: JCR-4355-jr.diff, JCR-4355-v2-javadoc-html.zip, > JCR-4355-v2.patch, JCR-4355.diff > > > Here are some changes to the javadocs for the new API: > [OAK-7569-api-javadoc-improvements.patch|https://issues.apache.org/jira/secure/attachment/12934364/12934364_OAK-7569-api-javadoc-improvements.patch] > * more concise descriptions > * correcting some inaccuracies (clients cannot choose whether to do single or > multipart upload, multipart might be strictly required depending on the size) > * most importantly the upload algorithm (standard partSize calculation was > wrong) > * focus on API users, separated notes to implementors > * for BinaryDownloadOptions added note from which jcr properties a client > would normally take these values from > * added security considerations -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Updated] (JCR-4355) Javadoc fixes and improvements for new direct binary access API
[ https://issues.apache.org/jira/browse/JCR-4355?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Julian Reschke updated JCR-4355: Fix Version/s: 2.18 > Javadoc fixes and improvements for new direct binary access API > --- > > Key: JCR-4355 > URL: https://issues.apache.org/jira/browse/JCR-4355 > Project: Jackrabbit Content Repository > Issue Type: Improvement > Components: jackrabbit-api >Reporter: Alexander Klimetschek >Assignee: Julian Reschke >Priority: Major > Fix For: 2.18 > > Attachments: JCR-4355-v2-javadoc-html.zip, JCR-4355-v2.patch, > JCR-4355.diff > > > Here are some changes to the javadocs for the new API: > [OAK-7569-api-javadoc-improvements.patch|https://issues.apache.org/jira/secure/attachment/12934364/12934364_OAK-7569-api-javadoc-improvements.patch] > * more concise descriptions > * correcting some inaccuracies (clients cannot choose whether to do single or > multipart upload, multipart might be strictly required depending on the size) > * most importantly the upload algorithm (standard partSize calculation was > wrong) > * focus on API users, separated notes to implementors > * for BinaryDownloadOptions added note from which jcr properties a client > would normally take these values from > * added security considerations -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Assigned] (JCR-4355) Javadoc fixes and improvements for new direct binary access API
[ https://issues.apache.org/jira/browse/JCR-4355?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Julian Reschke reassigned JCR-4355: --- Assignee: Julian Reschke > Javadoc fixes and improvements for new direct binary access API > --- > > Key: JCR-4355 > URL: https://issues.apache.org/jira/browse/JCR-4355 > Project: Jackrabbit Content Repository > Issue Type: Improvement > Components: jackrabbit-api >Reporter: Alexander Klimetschek >Assignee: Julian Reschke >Priority: Major > Fix For: 2.18 > > Attachments: JCR-4355-v2-javadoc-html.zip, JCR-4355-v2.patch, > JCR-4355.diff > > > Here are some changes to the javadocs for the new API: > [OAK-7569-api-javadoc-improvements.patch|https://issues.apache.org/jira/secure/attachment/12934364/12934364_OAK-7569-api-javadoc-improvements.patch] > * more concise descriptions > * correcting some inaccuracies (clients cannot choose whether to do single or > multipart upload, multipart might be strictly required depending on the size) > * most importantly the upload algorithm (standard partSize calculation was > wrong) > * focus on API users, separated notes to implementors > * for BinaryDownloadOptions added note from which jcr properties a client > would normally take these values from > * added security considerations -- This message was sent by Atlassian JIRA (v7.6.3#76005)
