Server has native java classes delivered as JAR file, javadoc, examples on java language. Before reading we recommend you to read Terms, Security and Error handling.

A reference

At MAVEN SITE you can find:

• apidocs
• source codes
• instructions for including the library to your projects at Dependency and Repositories page for various types of build engines
• you can also manually download the JAR files (after getting username/password from support team) from https://dev.srv4pos.com/nexus/content/repositories/releases/com/srv4pos/server/server-api/

Samples and test runs

In addition to API classes, server-api.jar contains specail tool called Diagnostics:

1. This is central place to find all the samples: it calls classes such as TaxServiceSample, ProductServiceSample etc.
2. You can use it to verify is your environment properly configured to be able to talk to the server by running all those sample one by one. Just run java -jar server-api-{version}-jar-with-dependencies.jar http://servername.com true
3. You also can run Diagnostics from your java app for testing purpose. Do it each time you think there is a bug on the server before sending bugreport to srv4pos support team 😉

Where to start?

There is a lot of classes in the api. Is there any place where I can start from?

• Use Diagnostics sources to copy it’s source code into your app.
• Use ServiceFactory (src) to get access to all API. It’s a signle entry point to the API. It is lightweight. Which means you can create it pretty often by demand.
• Carefully read further 🙂

Naming conventions

• *Service classes provide the functionality. They are also lightweight.
• *ServiceSample classes provides corresponding samples.
• *Info classes are Data Transfer Objects, they are basic POJO – a data structures.
• *AdvancedInfo class is an extention for a particular *Info class. For instance CommodityInfo might have own extention as CategoryAdvancedInfo. But it’s restricted to have FooAdvancedInfo without having FooInfo. The motivation for having (for example) BarAdvancedInfo if BarInfo have field “String foo” which is basically a string identifier to Foo entity. But sometimes we need to get a full structre at one call. So we want to have “Foo foo” instead of “String foo”. Assuming we need both we have BarAdvancedInfo which contains “Foo foo” and BarInfo which contains “String foo”. Compare CommodityInfo and CategoryAdvancedInfo.
• *ReplyInfo are dummy classes for few methods which returns a single value. By convention we have to return a structure, not a single value. Therefore we have to have those kind of classes.
• *JsonException is an exception thrown by server. It’s explained bellow and at Error handling.
• *Helper classes also provide the functionality similar to Services but do not work with a remote.
• *Utils classes have the same semantic as many similar classes from apache-commons.

Few more tips

• Server time is UTC. When it’s needed to pass some date, round time to 0:00:00:000 in UTC. It’s some sort of validation that you use right timezone.
• There is a very usefull class Registry. Use it! See example of it’s usage in Diagnostics, method main. By using it you have a guarantee server version matches to your version. If it’s not, server gracefully throw OutdatedVersionJsonException instead of breaking your logic. Also you can get the actual URL of cloud servers with the method Registry.getCloudServerUrl(boolean development) .
• If you don’t know what to use as Transport passed to ServiceFactory, use HttpUrlTransport.
• Curious which Credentials to use?
  • Use ActivationCredentials if you are not human. E.g. when you develop an integration module for your software . When you want to send data to Control Unit. When you send receipts to the server from your POS terminal.
  • Use SellerUserCredentials if you have a user profile on the server (username, password).
  • Use SellerCredentials if you don’t have any particular account. In this case only the public data will be available.
• In case of ActivationCredentials is used, the server requests seller version when you create, edit or delete information. Don’t forget to provide it. Read Synchronization and Caching for more info.
• Remember, that if you have an ability to keep some data in your local storage (e.g. memcached) or in memory (HashMap ?), do that to increase performance! Save sellerVersion together with the data and provide it to methods which return the data. If those methods return null instead of empty array – it means server don’t have any new (updated) data so you can reuse the data from your local cache.

Date & time

All data & time is always in UTC.

Activation module

Class diagram

Proguard/DEX config

• # server-api -dontwarn javax.validation.* -dontwarn javax.validation.constraints.* -dontwarn org.aspectj.lang.* -dontwarn org.aspectj.lang.annotation.* -dontwarn org.aspectj.internal.lang.annotation.* -keep class com.pos4mobile.server.api.** { *; } -keeppackagenames com.srv4pos.server.api.activation.** -keep class flexjson.** {*;} -keepclassmembers class flexjson.** {*;}

  1 2 3 4 5 6 7 8 9 10 11 12 13 # server-api -dontwarn javax.validation.* -dontwarn javax.validation.constraints.* -dontwarn org.aspectj.lang.* -dontwarn org.aspectj.lang.annotation.* -dontwarn org.aspectj.internal.lang.annotation.* -keep class com.pos4mobile.server.api.** { *; } -keeppackagenames com.srv4pos.server.api.activation.** -keep class flexjson.** {*;} -keepclassmembers class flexjson.** {*;}