Re: [xwiki-devs] [Proposal] Wiki API - xwiki-devs@xwiki.org

21 Oct 2013

Hi

2013/10/17 Eduard Moraru &lt;enygma2002(a)gmail.com&gt;

...
  Hi,

 On Wed, Oct 16, 2013 at 12:18 PM, Guillaume "Louis-Marie" Delhumeau <
 gdelhumeau(a)xwiki.com&gt; wrote:

  Hi Edy

 2013/10/11 Eduard Moraru &lt;enygma2002(a)gmail.com&gt;

  Hi,

 On Thu, Oct 10, 2013 at 11:46 AM, Guillaume "Louis-Marie" Delhumeau <
 gdelhumeau(a)xwiki.com&gt; wrote:

 > Hi Eduard,
 >
 >
 > 2013/10/9 Eduard Moraru &lt;enygma2002(a)gmail.com&gt;
 >
 > > Hi,
 > >
 > > On Tue, Oct 8, 2013 at 4:41 PM, Guillaume "Louis-Marie" Delhumeau
<
 > > gdelhumeau(a)xwiki.com&gt; wrote:
 > >
 > > > Thanks for all your answers.
 > > >
 > > > I continue to iterate until we reach something nice. You can see 
the
   work
 > > there:
 > >
 > >
 >

https://github.com/gdelhumeau/xwiki-platform/tree/feature-wiki-properties-g…
  > >
 >
 > Side note: I`ve noticed that you have 2 branches where you work, both
 > feature-wiki-properties-group that you`ve linked to now and  new-wiki-api
  > that you`ve linked to in the initial post.
Please use only one since  it`s
  > already quite confusing and hard to follow.
 >
 >
 > > > >
 > > > > I think my mistakes until now was the fact that I didn't want to
 > > deviate
 > > > > too much from the wiki-descriptor module of Vincent. But now, I
 > > > understand
 > > > > it is better to make something new.
 > > > >
 > > > > Now, the API has a complete javadoc.
 > > > >
 > > > > = Modularity =
 > > > > == Reduce responsibility ==
 > > > >
 > > > > The first advantage of creating several modules is to reduce the
 > > > > responsibility of each module. I want one API to handle the wiki
 > > creation
 > > > > and basic management, one API for the template feature (which 
could
   be
  > > optional as soon as we have flavors),
 >
 >
 > This transition will most certainly require some considerable  refactoring
  > and possibly some method deprecating, for
which we already have a
 strategy,
 > at least for the workspaces UI.
 >

 Currently, the workspaces UI is a kind of a hack.  WorkspaceManager.Install
  create a new template where we install a standard
XAR UI + Workspace
 Template Feature (that overwrites some standard pages) + delete some  pages
  that we don't need, etc... It forces us to
ask the user to create
 workspacetemplate first, it does not work out of the box. 

 Neither does wiki manager work out of the box. The current technical
 limitations require that the user first creates a template wiki that is
 used in the creation of new wikis/workspaces.

 Yes, and it is bad, IMO. Today, we have the Distribution Wizard which is
 launched the first time we go to the wiki. There is no reason to force
 having a template anymore.

 >
 >
 > > And we need to
 > > have 2 distinct XARs to handle the 2 use-cases: farm and workspaces.  It
   is
 > definitively not clean.
 >
 > When talking with Vincent about this, we decided that it would be  better
 > to
 > > create a unique XAR that handle the 2 use-cases.
 >
 >
 > But again, this does not fix the "out-of-the-box" issue.
 >
 >
 > > It will just look at the
 > > wiki configuration to know if we have local users or not, what is the
 > > membership type of the wiki, etc...
 > >
 >
 > The idea was that an admin could come with his own customized XAR that
 > would then be "adapted" to be used as a workspace template, if the 
admin
   did not
already do that. It was not desired that the user be limited to  the
 > standard XE xar, since that would have been rather easy to implement  and

automatically "install".

  About the ability to create a template that is automatically "adapted"
to
 be a workspace template, I have the feeling that there are more drawbacks
 than benefits:
 - it's too complex
 - it is useless for the majority of users
 - the wiki creation does not work out of the box
 - we have to write documentation about this...
 - If a user wants to create his own customized XAR, he can start from the
 default we provide

 You also need to be aware that when this application (workspaces) was
 developed, it was to be developed as an addon. Even the minor and almost
 necessary "hacks" (read "IFs") that were added into platform for the
top
 menus were frowned upon even to this date. Stating that the current
 implementation is not optimal when viewing this no longer as an added
 feature, but a basic and integrated feature is, basically, comparing apples
 to oranges.

 My only concern is that, whatever approach we chose, we preserve the
 ability of an admin to provide his own, customized, workspace template,
 either through a xar, a flavour or whatever, just as long as he still has
 the means to build it and deploy it (without having to publish it to a
 public extension repository, since it can be private stuff).

I understand. That is why I still have the notion of "wiki templates". An
admin can create a new template, customize it, and propose it at the wiki
creation.

...

   > > So, I apologize to not having
talk here about that. I think that we
 > should,
 > > indeed, refactor a lot of things to have a very clean multiwiki  feature
   in
 > 5.3.

 >   > > Basically, you`d
right now be using a
 > $services.wiki.createWiki('newWiki')
 > > to create the wiki followed by a
 > > $services.wikiTemplate.apply('someWikiTemplateName', 'newWiki')
to
 > > initialize the wiki with content.
 > > When we`d have flavours, you`d probably follow the creation step  with a
 > > > $services.extension.install('someFlavourExtensionID', 
'newWiki')  to
    > initialize the wiki with the content of a flavour
extension.
 > We`d probably also want to keep the option of importing the content  from
 > a
 > > XAR, so that might be a option too.
 >   > > So this wikiTemplate
service would probably contain some methods  like:
  > > - create/convert (since the argument
would probably be a wikiID to  mark
  > as
 > > template. The content of that wiki would have previously be  initialized
   > from
an extension of from a XAR)

 I have proposed setTemplate(boolean template);

 Maybe setTemplate(String wikiID) as in,
 $services.wikiTemplate.setTemplate('someWiki')

 ...or even setTemplate(String wikiID, boolean isTemplate) to avoid  having a
  second removeTemplate(String wikiID) method.

 Yes, I like this one.

 > > - list/getAll (wikis marked as templates)
 > > - delete/revert (remove the template mark, resulting in a regular  wiki
  > once
 > > again)
 > > - isTemplate (wikiID)
 > > - apply (as seen above, copy the content to an empty wiki)
 >  
   > I was thinking about createWikiFromTemplate() instead, but
maybe it  does
   not
provide enough flexibility.

 Didn`t you mention something earlier about separation of concerns? :)

  I see the template feature as an helper for the creation of a wiki. We
 don't need template for anything else than the creation of a wiki. So it
 does not disturb me to have createWikiFromTemplate() (which internally  call
  createWiki).

 >  
 > >   > >
> Side Note1: It could get a bit ugly fast when having to list wikis.
 > What
 > > do
 > > > you do with templates? What do users see, what do admins see if you
 > plan
 > > to
 > > > have a single view(UI) for everything? Probably 2 UIs would fit 
best
   > >
(similar to what we have not with WikiManagerUI and WorkspacesUI).  The
 > > > WikiManager part would probably go in the main wiki's 
administration
   (for
 > > admins) and the WorkspacesUI part would be in the main wiki's 
WikiIndex
 > > > (for users).
 > >  
 >   > > That is an interesting question. I did not think that
much about the  UI
    until now. I wanted to have a clean API first.

 I propose, with Caty:
 * 1 UI which is the "Wiki Directory" that display only wikis that users 
can
  use
  * 1 UI, in the administration, to manage templates only.

 > >  
 > > >   >
> > > Side Note2: While thinking about templates, I thought that we might
 > > need
 > > > > some "copy" and "rename" methods for the
WikiManager API, since
 they
  > > might
 > > > operations that the user might want to perform without having to 
use
 > > > > templates or some other weird operations.
 > > >  
 > >   > > > - Rename would be hard to
implement (copy the wiki and delete it?)
 > >  
 >   > > No, just rename the database and the descriptor. Is
there any
 limitation
 > to
 > > that?
 >  
 >   > There is nothing in the XWikiStoreInterface to rename a
database.
   > - DB2 does not support the database
renaming:
 > http://bytes.com/topic/db2/answers/185194-i-want-rename-table-schema
 > - Derby neither:
 > http://apache-database.10148.n7.nabble.com/Rename-Schema-td95708.html
 > - Neither oracle:

 http://asktom.oracle.com/pls/asktom/f?p=100:11:0::::P11_QUESTION_ID:3002019…
   > But it's OK for PostGreSQL, MySQL
and HSQLDB.
   > So, if we want to rename the database
from A to B, we can:
 > - create the database B
 > - import all the data from A into B
 > - delete the database A.

 We had the same problem with renaming documents. We did not take it into
 account in the initial API/model and then we had to fake it with a
 delete+remove. If we have to do the same for wikis, fine, but IMO we have
 to include these common sense operations or we will hit them in the future
 and we will be forced to do even dirtier things, or worse, leave the user
 to have to do them.

 Also, implementation would not be hard (we already do wiki copy and
 delete). We`d just need to be careful :)

OK.

...

   - What
"copy a wiki" means? Should we copy the history of every pages  too?
 > Should we copy the recycle bin? I did not want to provide a copy  feature
 > > because of these questions. The template feature actually does a copy
 > > operation but with its own opinion concerning this aspects : no  history
    copied, no recycle bin.

 1-to-1 copy of the source wiki. This means everything.

 Sure, there might be some applications that use custom mapping and add  some
  tables to the source database that might not be
copied in the process.  But,
 > if we have no way of detecting and copying this data, I think it's not  a
   bit
problem. History and recycle bin are core notions of which we have  full
  control so they should not be an issue.

 Then we need an option to not copy history and recycle bin, because when
 you create a wiki from a template, you don't care about deleted documents
 and the history. Only the template creator needs them.

 Anyway, since we`re reviewing these processes and thinking about them  now,
  maybe we should do it right. Copy and Rename are
basic operations that
 should not miss from any data model. 

 I agree.

  We should *at least* include them in
 the API and implement them when time allows (and expose them in the UI  when
  implemented). It would be a shame to have yet
another half baked API.

 Can we create an implementation with missing features?

 We do things iteratively. I don`t see why we can`t apply that to
 implementations of an API, as long as we don`t have any UI using it, thus
 risking to crash.

OK.

Thanks,
Louis-Marie.