Data injector is used to create data for the performance benchmark. This part will describe which data injectors are implemented in eXo Knowledge and how to use them.	

h1. Technical details {anchor:id=KSref.Configuration.Data_Injector_Service.Technical_details}

In eXo Knowledge, data injectors are implemented as plugins attached to the org.exoplatform.services.bench.DataInjectorService service. This service is normally registered to the portal container as a general component and handled via RESTful requests.

To use this service, add the following dependency to the Classpath of the server:

{code:xml}
<dependency>
  <groupId>org.exoplatform.commons</groupId>
  <artifactId>exo.platform.commons.component</artifactId>
  <version>${org.exoplatform.commons.version}</version>
  <scope>provided</scope>
</dependency>
{code}

When you want to inject data for a specified product, you will have to implement a class which extends _org.exoplatform.services.bench.DataInjector_ and register it to _DataInjectorService_ as a plugin. 

In which, methods need to be installed are:

{code:java}
public abstract class DataInjector extends BaseComponentPlugin {
 
  /**
   * get log object.
   * @return
   */
  public abstract Log getLog();
 
  /**
   * This function should be implemented to execute tasks that require to response data to client.
   * <br>
   * @param params query parameters of a HTTP GET request.
   * @return object that can be serialized to JSON object.
   * @throws Exception
   */
  public abstract Object execute(HashMap<String , String> params) throws Exception;
 
  /**
   * This function should be implemented to inject data into the product.
   * @param params parameters for injecting. They can be query parameters of a HTTP GET request.  
   * @throws Exception
   */
  public abstract void inject(HashMap<String , String> params) throws Exception;
 
  /**
   * This function should be implemented to clear data that is injected before by {@link #inject()}.
   * @param params parameters for rejecting. They can be query parameters of a HTTP GET request.
   * @throws Exception
   */
  public abstract void reject(HashMap<String , String> params) throws Exception;
{code}


h1. Configuration {anchor:id=KSref.Configuration.Data_Injectior_Service.Configuration}

To activate _DataInjectorService_, you must register this component to a portal container by the following configuration:

{code:xml}
<component>
  <type>org.exoplatform.services.bench.DataInjectorService</type>
</component>
{code}

In eXo Knowledge, there are three plugins attached to the _DataInjectorService_ component:
* ForumDataInjector
* WikiDataInjector
* AnswerDataInjector


h2. ForumDataInjector {anchor:id=KSref.Configuration.Data_Injectior_Service.Configuration.Forum_Data_Injectior}

The Forum Data injector is configured to register to DataInjectorService by the following code:

{code:xml}
<external-component-plug-ins>
  <target-component>org.exoplatform.services.bench.DataInjectorService</target-component>
  <component-plug-in>
    <name>ForumDataInjector</name>
    <set-method>addInjector</set-method>
    <type>org.exoplatform.forum.bench.ForumDataInjector</type>
    <description>inject data for Forum</description>
  </component-plug-in>
</external-component-plug-ins>
{code}

* To inject data, the request link is in the following format:

{code}
http://[rest-path]/bench/inject/ForumDataInjector/?type=data&q=10,20,30,40,50&pre=cat,for,top,post,att&attSize=1
{code}

The query parameters description:

|| Param || Value || Description ||
| q	| Number | The quantity of each item in forum. For example, if the value is 10,20,30,40,50 then the injector will create 10 categories, each category will have 20 forums, each forum contains 30 topics, each topic has 40 posts which contains 50 attachments in each posts. |
| pre | String | The prefixes of category, forum, topic, post and attachment. If "cat,for,top,pos,att" is inputed, the injector will create a set of data inlcude: categories with "cat" prefix, forums with "for" prefix and so on. |
| attSize | Number | The size of each attachment which is created in a post. |

* Every created topic can only  be read/modified by user 'root' to grant permission to other members.


h2. Wiki Data injector  {anchor:id=KSref.Configuration.Data_Injectior_Service.Wiki_data_injectior}
The Data injector for Wiki is configured as follow:

{code:xml}
<external-component-plug-ins>
  <target-component>org.exoplatform.services.bench.DataInjectorService</target-component>
  <component-plug-in>
    <name>WikiDataInjector</name>
    <set-method>addInjector</set-method>
    <type>org.exoplatform.wiki.bench.WikiDataInjector</type>
    <description>inject data for Wiki</description>
  </component-plug-in>
</external-component-plug-ins>
{code}

* To inject data, the request link is in the following format:

{code}
http://[rest path]/bench/inject/WikiDataInjector/?type=data&q=1,2,3&pre=abc,def,mnp&wo=classic&wt=portal&maxAtt=10&mP=100
{code}

In which, parameters mean:

|| Param || Value || Description ||
| type | {noformat}[data | perm]{noformat} | Type of injector. It can be data or perm which injects data or permission respectively. |
| q | Number | The number of pages in each depth, separated by commas. For example, if value is 1,2,3 then the injector will create 1 new child of WikiHome, 2 children per each page created in depth 1 and 3 children for each page created in depth 2. |
| pre | String | Prefix for page id in each depth, separated by commas. For example, if value is abc,def,ghk then pages in depth 1 have title starting with "abc", title of pages in depth 2 start with "def" and in depth 3 is "ghk". |
| wo | String | Wiki owner. |
| wt | String | Wiki type. The value can be: 'portal', 'user', 'group'.|
| maxAtt | Number | The size of attachment in created pages. the value is evaluated in KByte. If the value is 0 or not set, no attachment is created. |
| mP | Number | The maximum pages in each injection. The number of created pages must not exceed this value. |

To grant permision, the request link is in the following format:

{code}
http://localhost:8080/rest-ksdemo/private/bench/inject/WikiDataInjector/?type=perm&q=1,2,3&pre=abc,def,ghk&wo=classic&wt=portal&perm=11&users=root,mary&groups=*:/platform/user&rcs=true
{code}

For instance, in the link above, the injector will set the Read and Edit permission for pages of portal/classic which meet the constraint (q=1,2,3 and pre=abc,def,ghk).

You can use these parameters to set up permissions for pages:

|| Param || Value || Description  ||
| q  | Number | The number of pages in each depth separated by commas. For example, if value is 1,2,3 then the injector will create 1 new child of WikiHome, 2 children per each page created in depth 1 and 3 children for each page created in depth 2. |
| pre | String | The prefix for page id in each depth separated by commas. For example, if the value is "abc,def,ghk" then pages in depth 1 will have title starting with "abc", title of pages in depth 2 will start with "def" and in depth 3 is "ghk"
| wo | String | The wiki owner separated by commas. |
| wt | String | The wiki type separated by commas. This value can be: portal, user or group. |
| users | String, | The list of granted permissions users separated by commas. |
| groups  | String | The list of granted permissions groups separated by commas. |
| memship | String | The list of granted permissions memberships separated by commas. |
| perm | [number][number] | The declared permissions. The value must be a string with 2 numbers. The first number is to define Read permission of identity while the other one is for Edit permission. If the number is "zero", the privilege is denied and vise versa. For example, 11 means that both Read and Edit pages permmission are granted. |
| rcs | Boolean | Recursive or not. If the value is true, all pages that meet the constraint will be set permission, or deepest pages (smallest descendants) will be affected. |

h2. AnswerDataInjector {anchor:id=KSref.Configuration.Data_Injectior_Service.Answer_data_injectior}

The following configuration is used for the Answer Data injector:

{code:xml}
<external-component-plug-ins>
  <target-component>org.exoplatform.services.bench.DataInjectorService</target-component>
  <component-plug-in>
    <name>AnswerDataInjector</name>
    <set-method>addInjector</set-method>
    <type>org.exoplatform.faq.bench.AnswerDataInjector</type>
    <description>inject data for Answer</description>
  </component-plug-in>
</external-component-plug-ins>
{code}

* To inject data, the request link is in the following format:

{code}
http://[rest path]/bench/inject/AnswerDataInjector/?type=data&q=2,3,4,5,6&pre=cate,ques,answ,comm&att=2&attCp=100&&txtCp=100
{code}

In which:

|| Param || Value || Description ||
| type | [data | perm] | Type of injector. It can be data or perm means injecting data or permission respectively. |
| q | number,number,etc | The number of items in each depth. For example, if the value is 2,3,4,5,6 then the injector will create 2 new categories with the depth level is '3', add 4 questions in each category, 5 answer and 6 comment in each question. *Warning*: Do not set the depth level to more than 5, because the number of items are calculated by {noformat}number*depth{noformat}.|
| pre | string, string, etc | The prefix for items id in each depth. For example, if the value is "cate, ques, answ, comm" then category has fist name/id is "cate", question has fist name/id is "ques", answer has fist id is "answ" and comment has fist id is "comm" . | 
| att | number | The number of attachments in one question. If the value is '0' or not set, no attachment is created. |
| attCp	| number | The capacity of one attachment. The value is evaluated in KByte and must be larger than KByte. |
| txtcp	| number | The capacity text of one item (question/answer/comment). The value is evaluated in KByte. If the value is 0 or not set, texts are created randomly. |

{note}
All number of item injectors are calculated by:
*  Categories: cats = numberCat * depth!
*  Questions : ques = cats * numberQue
*  Answers : anss = quest * numberAns
*  Comments : coms = quest * numberComs

All = cats + ques + anss + coms

For example:

q=2,3,4,5,6: All = 2 * 3! + (2 * 3!) * 4 + ((2 * 3!) * 4) * 5 + ((2 * 3!) * 4) * 6 = 588 (items)

If you change the depth from '3' to '5', the number of items will be 11760.
{note}

* To grant permision, the request link is in the following format:

{code}
http://[rest path]/bench/inject/AnswerDataInjector/?type=perm&q=2,3,4,5,6&pre=cate,ques,answ,comm&att=2&attCp=100&&txtCp=100&view=root,demo,*:/platform/user&edit=root,*:/platform/manager
{code}

In which:

|| Param ||  Value  || Description  ||
| view | string, string, etc | The list of granted permissions users/groups/memberships, if the value is "any" or not set, everyone can view all category create by prefix. | 
| edit | string, string, etc | The list of granted permissions users/groups/memberships, if the value is "any" or not set, only user with highest permission (Administrator) can edit all category create by prefix. | 
	
{note}
In the other way, such settings have been declared in "ksdemo.war/WEB-INF/conf/ksdemo/ks/bench-configuration.xml", therefore, to save time and effort, you can import it to "ksdemo.war/WEB-INF/conf/configuration.xml" and then modify it rather than create new one.
{note}

h1. How to use? {anchor:id=KSref.Configuration.Data_Injectior_Service.How_to_use}

You can use RESTful service to request to inject or reject data. The format of request link is:

{code}
http://{domain}/{rest}/bench/{inject|reject}/{plug-inName}?[params]
{code}

For example, after registering the WikiDataInjector plug-in as above, you can request injection as follows: http://localhost:8080/rest-ksdemo/bench/inject/WikiDataInjector?mP=10&mA=100&mD=1&rand=false&wo=classic&wt=portal with 10 childrens of each page created, 100 kb each attachment, 1 depth level for wiki portal classic.

To reject such created data, request this link: http://localhost:8080/rest-ksdemo/bench/reject/WikiDataInjector.

