Źródła danych

Źródła danych to komponenty umożliwiające dokonywanie operacji na danych, takich jak odczyt danych, zapis, usuwanie lub modyfikacja. Źródłem danych może być tabela w bazie danych, zapytanie do bazy danych, plik na dysku, webservice, itp.

Źródła danych nie komponentami samowystarczalnymi, tak jak inne komponenty. Mogą one natomiast być wykorzystywane w innych komponentach. Dla przykładu może to być Datachooser, który wyświetla dane wybranego źródła danych.

Definiowanie źródła danych

Źródła danych tworzone są w oparciu o ich definicję stworzoną przez użytkownika. Definicja taka musi zawierać następujące elementy:

1. Adnotację @DataSource (jeżeli źródło danych nie jest definiowane we wtyczce, musi ona pochodzić z pakietu com.suncode)
2. Publiczną metodę oznaczoną adnotacją @Define z jednym parametrem DataSourceDefinitionBuilder
3. Publiczną metodę o nazwie datasource, która odpowiada za zwrócenie implementacji DataSourceInstance z logiką źródła danych.
4. (opcjonalnie) Publiczną metodę o nazwie validator, która odpowiada za zwrócenie implementacji DataSourceValidator z logiką walidacji deklaracji źródła danych.

Definicja może zawierać również adnotację @DataSourceScript. Adnotacja ta przekazuje ścieżkę do skryptu (z classpath) zawierającego definicję formularza dynamicznego.

Można również przekazać ścieżkę do skryptów, które chcemy użyć na formularzu. W tym celu należy użyć adnotacji @DataSourceInjectScript. Można przekazać ścieżki do wielu skruptów podajęc je w formie @DataSourceInjectScript({skryptPath1, skryptPath2, ..})

Źródło danych może również dostarczać skrypt, który buduje wygląd parametrów podczas jego definiowania w PWE. W tym celu należy dodać kolejną adnotację dla klasy @ComponentsFormScript z przekazaną ścieżką do skryptu (z classpath).

Przykładowa definicja przedstawiona jest poniżej.

@DataSource
@DataSourceScript("js/datasource.js")
@ComponentsFormScript( "path/example-form.js" )
public class DataSourceExample
{
    @Define
    public void definition( DataSourceDefinitionBuilder builder )
    {
        builder
            .id( "example-datasource" )
            .name( "datasource.example" )
            .description( "datasource.example.desc" )
            .category( Categories.TEST )
			.operations( DataSourceOperation.READ )
            .parameter()
                .id( "tableName" )
                .name( "datasource.parameter.tableName.name" )
                .description( "datasource.parameter.tableName.desc" )
                .type( Types.STRING)
                .create();
    }
 
    public DataSourceInstance datasource( @Param String tableName )
    {
        return new DatabaseTableSource( tableName );
    }

    public DataSourceValidator validator() {
        return new TableSourceValidator();
    }

}

Implementacja źródła danych

Źródło danych musi posiadać metodę o nazwie datasource. Metoda może posiadać następujące typy parametrów:

• pojedynczy parametr źródłą danych - typ parametru musi być zgodny ze zdefiniowanym typem oraz musi być poprzedzony adnotacją @Param,
• parametr mapujący dwa parametry tablicowe (klucz, wartość) - typ parametru musi być typu java.util.Map<K,V>, gdzie K to zdefiniowany typ parametru komponentu będącego kluczem, a V to zdefiniowany typ parametru komponentu będącego wartością dla klucza. Parametr musi być oznaczony adnotacją PairedParam ze zdefiniowanymi właściwościami (key - id parametry będącego kluczem, value - id parametru będącego wartością).
• pojedynczy parametr typu DataSourceInstance oznaczony adnotacją @Param - jeżeli posiadamy taki typ, to wstrzyknięty zostanie obiekt DataSourceInstance na podstawie wartości tego parametru, która musi być id źródła danych.
• Parameters - zawiera wszystkie zdefiniowane parametry walidatora wraz z ich wartościami, jest to alternatywa dla pobierania parametru za pomocą wyżej wspomnianej adnotacji@Param,
• Translator - translator dla tego komponentu, więcej informacji tutaj,
• UserInfo - obiekt zawierający informacje na temat użytkownika wykorzystującego źródło danych.

Metoda ta musi zwracać obiekt implementujący interfejs DataSourceInstance. Tak naprawdę ta implementacja powinna rozszerzać abstrakcyjną klasę AbstractDataSourceInstance, aby w przyszłości nie było błędów kompilacji, jeżeli będą dochodzić jakieś nowe metody do interfejsu DataSourceInstance.

Przykład implementacji:

public class DatabaseTableSource extends AbstractDataSourceInstance
{
	private String tableName;
 
	public DatabaseTableSource( String tableName )
	{
		this.tableName = tableName;
	}
    @Override
    public CountedResult<Map<String, Object>> getCountedData()
	{
		return new CountedResult<Map<String, Object>>(0, Maps.newHashMap())
	}
 
     @Override
     public void save( Map<String, Object> data )
     {
     }

     @Override
     public void update( Object key, Map<String, Object> data )
     {
     }

	 @Override
     public void delete( Object key )
     {
     }
}

Implementacja nie musi implementować wszystkich metod. Wymagane jest tylko pobieranie danych, gdyż nie każde źródło musi obsługiwać wszystkie operacji na danych.

Walidacja źródła danych

Źródło danych może opcjonalnie posiadać metodę o nazwie validator.

Metoda:

• jest bezparametrowa,
• zwraca obiekt implementujący interfejs DataSourceValidator,
• zwracany obiekt powinien rzucać wyjątek DataSourceValidateException w przypadku niepoprawnej deklaracji źródła danych.

Walidator jest wykorzystywany przy zapisie (utworzenie i aktualizacja) źródła danych.

Przykład implementacji:

public class TableSourceValidator implements DataSourceValidator
{
    @Override
    public void validate( DataSourceDeclaration declaration )
    {
        ParameterDeclaration someParam = declaration.getParameter( "someParam" );
        if ( !someParam.isArray() )
        {
            return;
        }

        ParameterValue someValue = someParam.getValue();

        if ( someValue.getValue().equals( "zła wartość" ) )
        {
            throw new DataSourceValidateException( "Wartość jest nieprawidłowa" );
        }
    }
}

Rejestracja źródła danych we wtyczce

Jeżeli źródło danych jest definiowane we wtyczce to należy dodatkowo zaznaczyć, że wtyczka ta udostępnia komponenty. W tym celu należy w pliku suncode-plugin.xml dodać wpis:

<!-- Udostępnianie zadań autoamtycznych--> 
<workflow-components key="components" />

Dynamiczny formularz

Dynamiczny formularz umożliwia zdefiniowanie formularza parametrów.

Rejestracja dynamicznego formularza

PW.DataSources.register('system-database-with-build-param', { // Identyfikator źródła danych
	buildParams: function(form){ // funkcja `buildParam`, która zostanie wykorzystana do zbudowania formularza parametrów źródła danych
		form.addField('param-1');
		form.addTextAreaField('param-2');
		form.addCombobox({
    		id : 'param-3',
    		values : [{id : 'activity', display : 'Activity'},
    		          {id : 'stage', display : 'Stage'},
    		          {id : 'process', display : 'Process'}]
    	});
		
		form.addTable(['param-4', 'param-5', 'param-6'], {
			tableId: 'fieldMap', name: 'Grupa', description: 'Grupa pól'
		});
 	}
});

Dostępne funkcję dynamicznego formularza

...
form.addField('param-1');
...

...
form.addField({
	id: 'custom',
	type: 'date',
	...
});
...

...
form.addTextArea('param-1');
...

...
form.addTextArea({
	id: 'param-1',
	...
});
...

...
form.addCombobox({
	id: 'param-1',
	valueField: 'id',
	displayField: 'display',
	fields: [
		{name: 'id', type: 'string'},
		{name: 'display', type: 'string'}
	],
	values : [{id : 'activity', display : 'Zadanie'},
		  {id : 'stage', display : 'Etap'},
		  {id : 'process', display : 'Proces'}],
	sort: [{
		property: 'display',
		direction: 'DESC'
	}],
	onChange: function(combo, newValue, oldValue){
		...
	}
});
...

...
form.addCombobox({
	id: 'param-1',
	valueField: 'id',
	displayField: 'display',
	fields: [
		{name: 'id', type: 'string'},
		{name: 'display', type: 'string'}
	],
	remote: {
		url: Suncode.getAbsolutePath('plugin/com.suncode.example-plugin/example-combo/get'),
		remoteSort: false,
		pageSize: 20
	},
	sort: [{
		property: 'display',
		direction: 'DESC'
	}],
	onChange: function(combo, newValue, oldValue){
		...
	}
});
...

...
form.addCheckbox('param-1');
...

var table = form.addTable();
table.addField('param-1');
table.addField('param-2');
table.addCombobox(...);

var row = form.addRow();
row.addField('param-1');
row.addField('param-2');
row.addCombobox(...);

form.addButton({
	id: 'btn-1',
	text: 'Przycisk',
	handler: function(){
	...
	}
})

...
form.addTextPassword('param-1');
...

...
form.addPassword({
	id: 'param-1',
	...
});
...

...
form.hide('param-1');
...

...
form.show('param-1');
...

...
form.getValue('param-1');
...

...
form.setValue('param-1', 'value');
...

@ComponentsFormScript( "actions/example-form.js" )

Cache

• Cache jest dostępny dla każdego typu źródła
• Cache może być włączony (i ustawiony czas) dla konkretnej definicji źródła. Decyduje o tym użytkownik w GUI
• Po aktualizacji systemu bez wchodzenia w zakładkę źródeł danych domyślnie wszystkie wtyczki maja cache wyłączony

• W builderze wtyczki (DataSourceDefinitionBuilder ) można skonfigurować parametr supportsPagination,  który określa czy wtyczka sama obsługuje paginację. Domyślnie jest ustawiony na true.

• jeśli jest włączony cache i paginacja po stronie systemu - pobierane są wszystkie wyniki z DSa nie przekazując paginacji, cachowane są i kolejne wywołania brane są z cache'a (paginując programowo)
• jeśli jest wyłączony cache i paginacja po stronie systemu - za każdym razem pobierane są wszystkie wyniki z DSa i paginacja nakładana jest programowo